GLL Text Selection

Returns and sets selection area.

Syntax

Gfa_SelCol [= c%]
Gfa_SelLine [= l%]
Gfa_SelectAll
g? = Gfa_IsSelection
sel$ = Gfa_Selection

Description

The bounds of an area of selected text in a GFABASIC program listing can be retrieved and set using Gfa_Line and Gfa_Col for the cursor position and Gfa_SelLine and Gfa_SelCol for the end of the selection.

When using these commands/functions, you need to bear the following in mind:

1. The values entered in or returned by Gfa_SelLine and Gfa_SelCol can mark a position in text either before or after the cursor position stored in or set for Gfa_Line and Gfa_Col; if the cursor is moved (perhaps using Gfa_Left) then it will be moved according to the coordinates returned by the Gfa_Line and Gfa_Col rather than Gfa_SelLine and Gfa_SelCol.


2. Any movement in the cursor position - either by directly setting Gfa_Col and Gfa_Line or by using any of the range of commands which move the cursor (Gfa_Left, Gfa_Right, etc.) - will reset the selected text resulting in Gfa_SelLine and Gfa_SelCol being set to the values contained in Gfa_Line and Gfa_Col respectively. So Gfa_Col and Gfa_Line need to be set BEFORE Gfa_SelCol and Gfa_SelLine, otherwise you will not get the selection you desire.


3. Values entered for the column properties (Gfa_Col and Gfa_SelCol) start at 0 and run to the number of characters in the line; this means that the value for the left most value is the number of characters BEFORE the selection starts and the value for the right most value is the character at the end of the selection. Hence setting the values to 2 and 5 respectively will result in the selection starting on the third character of the line, finishing on the fifth and containing three characters.


4. Values entered for the line properties (Gfa_Line and Gfa_SelLine) start from 1 and run to the number of lines in the listing (note that there may be a blank line or two at the end); the value entered for the lowest value property represents the first line of the selection and that for the highest represents the last line. Hence setting the values to 5 and 10 will result in the selection starting on line 5, ending on line 10 and consisting of 6 lines of program text.


5. With both column and line values, if the value assigned is too low or too high, it will be readjusted to fit the contents of the text; for example, if Gfa_Line is set to 0, it will be automatically corrected to hold 1 and if Gfa_SelCol is set to 16 and there are only 10 characters in the highlighted line, then the value of that property will be adjusted down to 10 to match.


6. To use Gfa_SelCol and Gfa_SelLine, you need to ensure that a value has been set for Gfa_Line and Gfa_Col first, otherwise no selection will be made.


7. To select one whole line, set Gfa_Col and Gfa_SelCol to zero and either the length of the line if known or _maxint (the maximum length of a line) if not.


8. To select mulitple lines, set Gfa_Line and Gfa_SelLine accordingly; however, if either the first or last line is not to be completely selected, remember to set the cursor position (Gfa_Col and Gfa_Line) first and then the end of the selection (Gfa_SelCol and Gfa_SelLine) afterwards.

Gfa_SelectAll selects the whole program listing, setting Gfa_Line to 1, Gfa_Col to zero, Gfa_SelLine to the number of lines in the listing (note there may be one or more blank lines at the end) and Gfa_SelCol to zero.

Finally, Gfa_IsSelection returns True when a valid selection has been made - and False othewise - and Gfa_Selection returns a string containing the currently selected text, if any. The text is returned in one long line of text with the CRLF (new line feed) characters removed.

Example

Sub Gfa_App_2

Debug.Clear

Gfa_Line = 0

Trace Gfa_Line                                        // Returns 1 (Gfa_Line can not be zero)

// Select part of a line

Gfa_Line = 2                                          // Select the ...

Gfa_SelLine = 2                                       // ...second line

Gfa_Col = 1                                           // Left of selection after character position 1 (the first space)

Gfa_SelCol = 5                                        // Right of selection upto and including 5

Debug Gfa_Selection                                   // " Deb"

Gfa_Col = 5                                           // Reverse the...

Gfa_SelCol = 1                                        // ...property values

Debug Gfa_Selection                                   // " Deb" (same as above)

// Select the whole of a line

Gfa_Col = 0

Gfa_SelCol = _maxInt                                  // Could be any value over 12

Trace Gfa_SelCol                                      // Returns 13 (the number of columns in the line)

Debug Gfa_Selection                                   // Returns the whole line "  Debug.Clear"

// Select multiple lines (lines 2 to 5)

Gfa_Line = 2

Gfa_SelLine = 5

Debug Gfa_Line, Gfa_Col, Gfa_SelLine, Gfa_SelCol      // Note the column values are zero

Gfa_Col = 4                                           // Set the selection to start AFTER the second character on line represeented by Gfa_Line...

Debug Gfa_Line, Gfa_Col, Gfa_SelLine, Gfa_SelCol      // Note that by setting Gfa_Col, Gfa_SelCol and Gfa_SelLine now equal Gfa_Col and Gfa_Sel

// Select multiple lines with staggered start and end markers

Gfa_Line = 4 : Gfa_Col = 3                            // Set the cursor position first (Gfa_Col and Gfa_Line)...

Gfa_SelLine = 7 : Gfa_SelCol = 2                      // ...then the end of the selection (Gfa_SelCol and Gfa_SelLine)

Debug Gfa_Line, Gfa_Col, Gfa_SelLine, Gfa_SelCol      // Show the values

// Moving the cursor...

Gfa_Left                                              // Move the cursor one place left (the cursor is at Gfa_Line, Gfa_Col)

Debug Gfa_Line, Gfa_Col, Gfa_SelLine, Gfa_SelCol      // Note the values for Gfa_SelCol and Gfa_SelLine are set to match Gfa_Col and Gfa_Line

// Select whole listing

Gfa_SelectAll                                         // Selects the whole program listing...

Debug Gfa_Selection                                   // ...and returns it in one long line without line breaks

Debug Gfa_Line, Gfa_Col, Gfa_SelLine, Gfa_SelCol      // Note the column values have been set to zero

Debug Gfa_IsSelection                                 // Returns True as there is a selection

// Clear selection

Gfa_Line = 1                                          // Remove the...

Gfa_SelLine = 1                                       // ..selection

Debug Gfa_IsSelection                                 // Now this returns False

EndSub

As with other GLL examples, copy and paste this example text into the GFABASIC IDE, compile it as a GLL and then add the file to the IDE under the Extras Menu ---> Extension Manager. To test it, press the App and 2 buttons (not the number pad 2) at the same time.

Remarks

Gfa_IsSelection is much faster then Len(Gfa_Selection); this is because, internally, Gfa_IsSelection is the same as (Gfa_SelLine != Gfa_Line || Gfa_SelCol != Gfa_Col)

See Also

GLL Cursor Movement, Gfa_Cut, Gfa_Copy, Gfa_CopyRtf, Gfa_CopyPre

{Created by Sjouke Hamstra; Last updated: 11/07/2023 by James Gaite}