Editing Clipboard Transformations

Root documentation of this application at: '''[[Python Smart ClipBoard]]'''  This page is the documentation for the details of the Transformations.

= General =
The application deals only with unformatted text in the clipboard.  Images.... are not processed.  Formatted text is converted ( irreversibly ) to unformatted text unless the off radio button is depressed before the selection is "clipped".  You can ususally return to the unformatted, untransformed version of the clipboard by pressing either <off> or <unformatted>.  If you press an unintended button, just go back and press the intended one.


A transformation takes in some text, typically multi-lined and converts it to something else, also possibly multi-lined.  The transformed text is placed in the system clipboard and displayed in the application GUI.  Each time a transformation button is pressed the original text in the clipboard is transformed.  To apply a new transformation to the result of the last transformation press the <Chain> button.  Once Chain is pressed the original clipped text is gone.

== Transformations Do What ==

You can tell what each transformation does by:

* Hopefully each name is suggestive <CAP> capitalizes the text.
* The GUI documentation gives a somewhat expanded explanation of each transformation [[ClipBoard GUI]] 
* Try them out, just do not "paste" results you do not like.
* More documentation here ?
* Read the code:  cmd_processor.transform_{some suggestive name }


* Some functions may remove blank lines.
* Some functions may remove lines commented with #

== General Rules ==

Most transformations ( and perhaps all in the future ) do some general processing:

* Break the text into multiple lines using a variety of markers ( see Python splitlines ), -- this is really a search and replace where we replace with \n
* Delete trailing spaces on each line 
* Joins lines back using a standard line marker ( cmd_processor.line_join ) by default the newline character \n    -- is this search and replace \n to nothing ( or to space )
* White space is used in the same sense as Python.  In includes spaces, tabs \n \r and other characters.

== Transformation Types ==

Ways of organizing transformations that may be used in some GUI versions, this is a new feature in progress

=== Search and Replace ===
* Search and replace ( some fixed one adjustable )
* do we want a join lines adjustable ??
* Advanced search and replace, almost search and replace but....
=== Line Operations ===
* Line operations, do something to lines, some work on pairs of lines
Add *>url
Add *>shell 

=== Pair Line Operations ===


=== Table of Transfromations ===

{| class="wikitable"
|-valign="top"
|What
|Does What
|Search/Replace
|Line Op
|Pair Line Op
|Command Op
|Wiki
<!-------------------------------->
|-valign="top"
|Add *>url
|Adds text "*>url" to each line.
|X
|
|
|X
|
<!-------------------------------->
|-valign="top"
|Add *>shell 
|Adds text "*>shell" to each line.
|X
|
|
|X
|
<!-------------------------------->
|-valign="top"
|Alt Line Sort 0
|Sorts line pairs using 0 line as key 
| 
|
|X
| 
|
<!-------------------------------->
|-valign="top"
|CAP
|upper case all
|X*
|
|
| 
|
<!-------------------------------->
|-valign="top"
|lower
|lower case all
|X*
|
|
| 
|
<!-------------------------------->
|-valign="top"
|Less WS 
|All white space to single space
|X*
|
|
| 
|
<!-------------------------------->
|-valign="top"
|Line Num
|Number the lines
| 
|
|X
| 
|
<!-------------------------------->
|-valign="top"
|No Blank Lines
| 
|X
|
|
| 
|
<!-------------------------------->
|-valign="top"
|No Trail Space
| 
|X
|
|
| 
|
<!-------------------------------->
|-valign="top"
|No WS
|X* 
| 
|
|
| 
|
<!-------------------------------->
|-valign="top"
|Add *new
| 
| 
|
|
| 
|
<!-------------------------------->
|-valign="top"
|Add *new
| 
| 
|
|
| 
|
<!-------------------------------->
|-valign="top"
|Add *new
| 
| 
|
|
| 
|
<!-------------------------------->
<!--------------------------------
<!--------------------------------
<!-------------------------------->
|}

=== Application View ===
* Text Edit
* Wiki work
* Command building






= Individual Transformations =



The GUI names should match those below, but use a bit of caution.  The order here is more or less alpha, not the order in the GUI.

== Add *>url ==
* What: Prefixes all lines with a url with "*>url"
* Why: to save url's in command format for later use with '''<*cmd>''' button
* Lines with a url have *>url pre-pended to the line.  This is the command indicator for the *cmd button to go to a given url.
* Lines without urls are left unaltered.

== Add *>shell ==
* What:  Prefixes all lines with *>shell ( or just lines with file names, need to check )
* Why:  Make it easy to store ( single line ) shell commands in files.

== Alt Line Sort 0 ==

* What:
* Why: I use this to sort url and page titles captured from my browser, typically saved for links 
* Text is broken up into pairs of lines, blank lines being dropped.
* The pair is sorted on the contents of the first line in the pair.
* The text is rebuilt with a blank line separating each pair.

== CAP ==
* What:  Capitalize all the text.
* Why:  Mostly to show off, this is actually not very useful for me.

== xxx ==
* What:
* Why:

== No Trail Space ==

* What: Remove all trailing white space.
* Why: Trailing white space is just a waste of space and may slow down code editing.


== Less WS ==

* What: Remove multiple white space characters in a row replacing them with a single space.
* Why:

== Line Sort ==

* What:  Sort lines in order.
* Why:  Some lists are just nice to have sorted.  Can help detect duplicates, but may have a dedicated transformation that deletes duplicates.

== Line Num ==

* What: Put sequential numbers in front of each non-blank lines
* Why: Sometimes nice to have you lines numbered.
== No Blank Lines ==
What:  Delete all blank lines.
Why:  Often blank lines are filler you just want to get rid of.

== No Trail Space ==

* What: Remove all trailing white space.
* Why: Trailing white space is just a waste of space and may slow down code editing.

== No WS ==

* What: Remove all white space.
* Why:  White space, for example can be a pain in the neck.  May have a transform that converts to underscores for a similar reason.

== Tab > Space ==

* What: Remove all tab characters changing them to spaces.
* Why: Python programmers tend to prefer spaces over tabs.  A mix of them can be confusing when editiong, and can cause Python programs that look correct to fail.


== still to do scratch  ==

off unformatted  Less WS indent *lines  comma, sep   delete dup   undent  alt line sort / sage delte /  url to wiki / wiki file upload 

== xxx ==
* What:  
* Why:  
* Lines  
* Lines

= Customization =

Writing your own Transforms is a bit more complicated than snippets or snips.  It involves code in two parts of the application.  One part does the transformation, the other provides the GUI.  The parameter file is not involved.  If you want to remove a transformation I would remove the GUI component only.  You can do this by commenting out the part of the code in gui.py.  This is more or less the reverse of adding a transform to the GUI.

== Transform Code ==

The text you get from the system is a string, and you modify it to return a string.  To do this you need to understand something about string handling in Python.  So we will assume this.  Before modifying code lets look at a simple example.

In your IDE for Python ( or text editor ) open cmd_processor.py.  All the transforms are functions named transform_xxxxxxxx.  Lets look at cmd_processor.transform_lower().  The heart of the code is: ret_text     = in_text.lower()
which simply uses the Python function to lower case.  The other two lines before the return do:

* Split the text to a list with one line in each list item, each line cleaned up a bit ( like stripping trailing spaces )
* Combine the lines into one long string.

The return is a tuple

* First a Boolean, it indicates the success of the operation.  This seems to be almost always True, as transformations "cannot fail".  I had some other ideas for this at one time.
* Second a string a comment on the operation.  Will be displayed in the message area of the GUI.
* Third a string, the transformed text.  Will place in the clipboard and displayed int the GUI below the comment.

To learn more about the transforms read the code, then write yours following the conventions in this one.

== GUI Code ==

You still need a button on the GUI to activate your code.  This will be in gui.py.  Look for a method called _make_transform_frame_().  In it is a section for each button, with a comment setting off each one.

Lets look at: 

<pre>


  # -------- transform_lower,
        ix_rb_index  += 1
        ix_col       += 1
        self.lower_rb   = ix_col

        self.make_and_place_transform_buttons_3 ( a_frame,  text = "lower",
                                   ix_row                   = ix_row, ix_col = ix_col,
                                   button_var               = self.button_var,
                                   button_command           = AppGlobal.cmd_processor.transform_lower,    
                                   rb_index                 = ix_rb_index )

 
</pre>

Your button will be pretty much the same inserted in order of where you want your button to occur in the GUI ( left to right, top to bottom ).

So:

* Make a copy of an existing button's code.  If the code differs a bit from the above go with the code not this documentation.
* Paste in where you want it.
* Change the comment line
* For the line that says self.lower_rb, make a new name for your radio button and put it in, or just get rid of the line if you do not need a name ( added buttons need not be named )
* AppGlobal.cmd_processor.transform_lower,   needs to have the name of your function replace transform_lower
* Save and if you have not messed up everything will work.








[[Category:Python Projects]] [[category:Python]] [[Category:ClipBoard]]