Introduction
Please Note: RunScreen
requires StringTheory
RunScreen allows the user to control certain elements of your program at
runtime. Specifically;
- Selecting, Hiding and re-arranging the columns of a list control at
runtime. This is a common feature of many programs, and indeed is a
native feature of Browses in Clarion's ABC library. RunScreen offers
an alternative implementation of this feature.
Features:
Column Management
Clarion already has browse column management in ABC.
(Don't know how to use it,
see here). So why use
a different one? It comes down to a matter of taste really, but these
are the reasons we created a different one;
- The visual design of the management window shown to the user is
declared inside the ABC Class (called ListFormatManagerClass)
inside a Private method. This means
the design will not conform to the other visual aspects of your
application. By contrast RunScreen requires this procedure to be in
your Application tree, so you have complete control over it.
- The ListFormatManagerClass allows
users to create multiple different layouts for each browse. In our
applications each user may want a different format, but allowing
them to create multiple formats for a single browse is overkill for
them. By contrast RunScreen offers a simpler interface.
- We already have template code (like Secwin) and hand-code in embed points that
manage which columns are visible or not. So we needed a List Manager
that worked in conjunction with that code and which allowed other
code to control the visibility of certain columns. Also that code
must work on the correct column, even if the column has been moved
by the user.
- Additional User-Interface features, like Drag
& Drop columns and Right-Click Hide-Column are
supported. (Note: Drag and Drop of
columns is not supported at this time because of changes in the
Clarion 9 event system. This functionality may or may not be
restored depending on the final state of Clarion 9.)
- Supports all List controls in addition to Browse controls.
One really interesting effect of having Runtime Column Management has
been that, as developers, we are more likely to add more fields to a
browse, even if those fields are hidden by default. There is less need
to exclude columns that have minimal usage, or which clutter up the
screen. We've found in our own apps that we're able to cater for a wider
variety of users, adding the columns that are only applicable to a few
users, while not cluttering up the browse for the others.
Jump Start
Legacy (Clarion) Template Chain
Make sure
Enable the Use of ABC
Classes is ticked on.
- Global Properties
- Classes Tab
- Enable Use of ABC Classes ON
Column Management - Single App system (ABC or Legacy)
- If you have the ABC List Format Manager currently on, then turn
that off on the Global Properties for the app, App Settings tab.
- Add the Activate StringTheory Global
Extension to the application.
- Add the Activate RunScreen Global
Extension to the application.
- Click on the Import SelectColumns Procedure
button
- Add the Activate Auto RunScreen Global Extension
OR
- (If you did Step 4, then you don't need to do this) Go to each
Browse Procedure which needs this feature. Highlight the Browse
Extension on the Extensions list, and Select Insert. Then select the
LocalRunScreenBrowse extension template.
You can just accept the defaults for this extension for now.
- (If you did step 4 then you don't need to do this) Go to each
(non-browse) List Control that needs this feature. Go to the
Extensions for that procedure and add the LocalRunScreenList
extension. Select the List Control for this extension.
As noted above you have the option to do step 4 (which applies RunScreen
to all the browses and lists in your app) or step 5 and/or 6 (which lets
you add RunScreen column management to just a few browses or lists) the
choice is yours.
Column Management - Multiple App system (ABC or Legacy)
Data DLL
- Apply the instructions for a Single app system (Steps 1 through
4) to this DLL.
- In addition, make sure both options on the Multi-DLL tab are on.
- Mark the imported RunScreenSelectColumns
procedure as Export.
Other DLLs and EXE(s)
- Add a procedure to the application, called RunScreenSelectColumns
and make it an External procedure exported by the Data
DLL.
The Prototype of this procedure should be
(String pFormat),String and the parameters should be (String pFormat).
- Add the StringTheory, RunScreen and Activate Auto RunScreen
Global Extensions but DO NOT click on the Import
SelectColumns Procedure button.
- DO go to the Multi-DLL tab, turn the first option on (This is
part of a Multi-DLL Program) but leave the second option OFF
(Export class from this DLL).
Code changes to your application
Runtime Effect in your Program
Column Management
Go to a browse which has the
LocalRunScreenBrowse
extension template. There are a number of features that have been added
to this browse;
- You can left-click-down on a column header,
and drag the column to another position. In other words you can
arrange the columns using Drag and Drop on the column headers.
- If you right click on a column header, you can choose Hide
Column to make that column hidden.
- If you right click anywhere on the header bar you can choose Columns... to get to the column formatter.
The column formatter allows you to;
- Re-order the columns by moving the columns up and down.
- Hide or unhide the columns by selecting checkbox to the left of
each column name.
- Set the Locked column (which locks horizontal scrolling so that
only columns to the right of that column are scrolled)
- You can also Reset the columns to their original configuration.
RunScreenSelectColumns
Procedure
Probably the key benefit to using RunScreen for column
management is the ability for you to control the look, and behavior of the
screen which the user will use to manage the columns.
The procedure itself can be imported into your application using the
button on the General tab of the Global extension. It consists of a simple
Window procedure and the RunScreen Select Columns Control template.
After importing the procedure you are free to change the properties of the
window and controls, you can add more controls and so on. Deleting the
controls that are there is not recommended (although they can be hidden if
you like.)
Because the procedure is in your application tree it will automatically
gain any local extensions that are being added to any procedure in your
application. For example if you are using
AnyFont or
Makeover in your application then these templates
will automatically be applied.
The template on this window currently has the following settings
User has to click on the checkbox to change the
value
If this option is on then the user has to click on the checkbox itself to
change the state of the column. If this option is off then clicking on any
part of the line will toggle the state of the checkbox.
Object Name
This is the name of the object used on this window. The default is
ThisSelectColumnsManager .
Saving User Choices
The choices the user makes needs to be saved
somewhere. You can save it in your applications INI file, or you can store
it in a database table. The INI file requires no overhead, but is local to
the machine, so if the user logs in from another machine their settings
won't be used.
A table is more effort to set up, but the settings are part of the data
set, so are backed up with everything else, and are applied regardless of
which machine the user uses to access the program.
This
is the recommended approach.
In order to save the settings in a table, you will need to add an
appropriate table to the dictionary.
The table requires the following fields (they can be any name, but all 3
fields are required);
| Field |
Type |
Comment |
| User |
String(100) |
Contains the user's login, so needs to be long enough to
accommodate that. |
| Procedure |
String (100) |
This contains an identifier for the browse, usually made up of
the procedure name and the RunScreen object name for that browse.
|
| Settings |
String |
This contains all the settings for the browse as a pipe
separated list. While the exact required length of this string
will be dependent on the number of columns in your widest browse,
a length of 2048 should be sufficient. Each column requires
approximately 25 bytes. |
The table also requires a
Unique Key, with
the
User and
Procedure
fields as components of that key.
A sample table, called RunScreen, has been supplied as a DCTX and can be
imported into your dictionary. This table can (should) then be adjusted to
use the same Driver as the other tables in your dictionary.
In order to apply this table to the Template, you will need to set the
options on the
Saving Tab of the RunScreen
Global
Extension in your application.
Designing Columns as Hidden by Default
In builds 1.21 and earlier a column could be "hidden
as default" if the width in the window designer was set to 0. This works
ok, but makes some functions problematic (like defining what width the
column should be when it appears.) From build 1.22 there is a new
property,
HiddenByDefault which allows the
programmer to explicitly set the correct width in the window designer, but
also set a column as being hidden by default.
To set a column as Hidden by default, the programmer only has to make 2
steps;
- Design the column in the Window formatter as you want it to appear
when it is visible. ie set the appropriate width etc.
- Go to the template extension, to the RunScreen extension, to the
Hidden tab. There you can select all the columns that should be hidden
by default.
Common Errors
- GEN: ASSERT: Add the StringTheory Global
extension to this app:
RunScreen requires StringTheory, so you need to add the StringTheory
global extension to the application in order for RunScreen to compile
correctly.
- Unresolved External CONSTRUCT@F11LISTMANAGER
(and about 60 others like it):
You have set the setting on the Multi-DLL tab of the global extension
indicating this is Multi-DLL system, but RunScreen is not being
exported by the Data DLL. Add RunScreen to the Data DLL and tick on
Export Class from this DLL there. StringTheory has to be set the same
way, so check that too.
- GPF on startup of a Legacy program:
Make sure the Enable the use of ABC Classes
option is on.
Deriving from ListManager Class and Using Derived
Classes
RunScreen provides a number of embed points where you
can embed your own code into the generated ListManager object. This
approach works well if you have a single app, and the code only needs to
go into one place. However if you are wanting to override the default
behaviour across multiple procedures, then the best approach is to derive
the ListManager class, adding your own code. Then that derived class can
be applied to the App. This section shows how to do both of those things.
Deriving the ListManager Class
Deriving a class consists of creating two new text
files. An INC and a CLW file. You can call these anything you like
(typically they have the same name, just a different extension.) These
files should be in the same folder as the
RunScreen.INC
and
RunScreen.CLW files. Usually this is
in
\clarion\accessory\libsrc\win. In the
examples below these files are called
CustomRunScreen.INC
and
CustomRunScreen.CLW.
INC File
The INC file contains very little boilerplate
code. Just a simple INCLUDE statement, and the derived class
declaration.For example;
include('RunScreen.Inc'),once
CustomListManager Class(ListManager), Type,
MODULE('CustomRunScreen.Clw'), |
LINK('CustomRunScreen.Clw',StringTheoryLinkMode),
DLL(StringTheoryDLLMode)
ErrorTrap Procedure(string pProc,string pStr),DERIVED
End
Note the MODULE and LINK point to your custom CLW file. You can use
the StringTheoryLinkMode and StringTheoryDLLMode
as is.
In this file, the INCLUDE at the top points to the parent-class
Include file, in this case RunScreen.Inc.
CLW File
The CLW file has a little more boilerplate, then
the custom methods are defined. You only need to derive the methods
you want to change, not the other methods.
member()
map
end
include('CustomRunScreen.Inc'),once
CustomListManager.ErrorTrap PROCEDURE (string pProc,string pStr)
code
message('yo yo ... no')
parent.ErrorTrap(pProc,pStr)
Note that in this file, the INCLUDE points to your custom include
file.
Using the Derived Class in an App
Using the derived class in an application is a
simple process;
- Go to the RunScreen Global Extension, to the Classes Tab. In the Additional
INC Files list add your custom INC file. In this example
CustomRunScreen.INC.
- Click the Refresh Classes button. Then click the
Classes button. You should see your new derived
class listed there.
- In the ListManager Class Name field select the
name of your derived class. In this case CustomListManager.
- If desired you can also override the global class name at the
procedure level, on the Class tab.
Template Reference
Global Extension - Activate
CapeSoft RunScreen
General Tab
Disable All RunScreen Features
Tick this on to disable all the RunScreen template code, and prevent
the code from being generated into your application. Typically used
for debugging when the RunScreen code is possibly causing conflicts in
your app.
Options Tab
Change Columns Procedure
This is the name of the procedure which contains the column selection
code. By default the procedure is called
RunScreenSelectColumns,
but you can rename it if you want to.
Use Secwin User
The columns are stored per user, meaning that one user can have a
different format to another user. In order to identify users some ID
mechanism is required. If you are using Secwin in your application
then tick this option on and the Secwin Login ID will be used.
Logged In User
If you are not using Secwin then enter an expression here which
contains the ID of the currently logged in user.
Translate Tab
Columns...
This option appears when you right click on a column header. It opens
the window which allows the user to format the columns. You can enter
different text here if you like (in quotes) or you can enter an
expression (such as calling your preferred translation engine.)
Hide Column
See Columns... above.
Saving Tab
For an explanation of your saving choices see
Saving User Choices.
Teh settings are stored in the INIfile, or table, using the Procedure
name as a unique identifier. If your system consists of multiple
different procedures with the same name (in different APP files) this
can be a problem. This setting, if set, adds a (presumably unique)
prefix to the Procedure name. This allows you to tailor the generated
procedure name so that the settings record in the INIfile, or Data
table, are unique.
Save in Application INI File
Tick this on to save the formats in the Application's INI file.
Save in Data Table
If you wish to save the settings in a table, then tick this on.
Table
Enter the name of the table here.
Key
Enter the name of the key here. This should be a unique key on the
User and Procedure fields.
User Field
Enter the name of the User Field here.
Procedure Field
Enter the name of the Procedure field here.
Settings Field
Enter the name of the Settings field here.
Multi-DLL Tab
This is part of a multi-DLL Program
If this app is part of a multi-app suite, then tick this option on for
all DLL's and EXE's in the suite. If your app is a single-app which
stands alone then leave this option off.
Export Class from this DLL
Only tick this option on if this is the Data DLL in your app system.
Classes Tab
Refresh Classes
Press this button if the RunScreen.Inc file, or any Additional INC
files, has changed, and needs to be re-loaded into the template.
Classes
Click on this button to see all the classes that have been attached to
RunScreen, and their methods.
Interfaces
Click on this button to see all the interfaces that have been attached
to RunScreen, and their methods. (At the time of writing this, there
were none.)
Additional Inc Files
If you have created any custom INC files, which contain classes that
will be used by RunScreen, add their names here. For more information
on deriving classes see
Deriving from ListManager
Class and Using Derived Classes.
All the local extension templates create a ThisListManager object. If
the class you want to use for this object is not ListManager, but one
of your derived classes, then you can select the name of the derived
class from the drop-down here. By default this choice will cascade
into all the procedures in the app, unless a different specific class
is chosen in the procedure's local extension.
Global Extension - Activate Auto
RunScreen
There are no prompts for this template. If you add
this template globally then the
Local
Auto RunScreen extension is added to all windows with a LIST
control.
Local Extension - Auto RunScreen
General Tab
Disable This Template
Tick this on to disable this template in this procedure. This can be
useful for debugging purposes.
Columns Tab
Do NOT do Column Management on
All the list controls on the window will be listed here. To prevent
RunScreen Column Management from applying to a list control highlight
it in the list. This is a multi-selection list, so you can suppress
multiple list controls at the same time.
Headers Tab
Usually the text from the column header is used in
the RunScreenSelectColumns procedure. However in some cases a column
may not have a header, or you may want an alternate text to be used
for the column selection. This list allows you to enter that alternate
text.
List Control
Select the List control which this header applies to here.
Column
Enter the column number here. This is the column number as at design
time.
Header
Enter the text as a fixed value (in quotes) or an expression which
should be displayed to the user when setting the column order.
Header
Class Tab
Object Name
The name of the list formatting object which will be used.
Class Name
The class to use for the object. The default is the ListManager class.
Local Extension for Browses
NOTE: Using the
Second Global Extension may be faster than applying this template
individually to lots of browses. See the
JumpStart
for more information.
General Tab
Disable This Template
Tick this on to disable this template in this procedure. This can be
useful for debugging purposes.
Headers Tab
Usually the text from the column header is used in
the RunScreenSelectColumns procedure. However in some cases a column
may not have a header, or you may want an alternate text to be used
for the column selection. This list allows you to enter that alternate
text.
Column
Enter the column number here. This is the column number as at design
time.
Header
Enter the text as a fixed value (in quotes) or an expression which
should be displayed to the user when setting the column order.
Set the Browse Header Text
Hidden Tab
When designing the list control the programmer may
choose to have some columns "hidden by default".
The columns should be added to the list control as normal, with their
correct width set, in the window designer. Then on template settings
they can be set as Hidden by Default.
when the list first displays the columns will not be visible. The user
can select them to display (in the usual way), but if they reset to
defaults then those columns will disappear.
Class Tab
Object Name
The name of the list formatting object which will be used.
Class Name
The class to use for the object. The default is the ListManager class.
Local Extension for List Control
NOTE: Using the
Second Global Extension may be faster than applying this template
individually to lots of browses. See the
JumpStart
for more information.
General Tab
Disable This Template
Tick this on to disable this template in this procedure. This can be
useful for debugging purposes.
List Control
Select from the list of controls on the window. The column management
will be applied to the selected control.
Headers Tab
Usually the text from the column header is used in
the RunScreenSelectColumns procedure. However in some cases a column
may not have a header, or you may want an alternate text to be used
for the column selection. This list allows you to enter that alternate
text.
Column
Enter the column number here. This is the column number as at design
time.
Header
Enter the text as a fixed value (in quotes) or an expression which
should be displayed to the user when setting the column order.
Hidden Tab
When designing the list control the programmer may
choose to have some columns "hidden by default".
The columns should be added to the list control as normal, with their
correct width set, in the window designer. Then on template settings
they can be set as Hidden by Default.
when the list first displays the columns will not be visible. The user
can select them to display (in the usual way), but if they reset to
defaults then those columns will disappear.
Class Tab
Object Name
The name of the list formatting object which will be used.
Class Name
The class to use for the object. The default is the ListManager class.
Using in a Multi-DLL System
In your Data-DLL:
- Add the Global Extension template, go to the Multi DLL tab and tick
ON both options;
This is part of a Multi-DLL program and
Export RunScreen Class from this DLL
- Add the RunScreenSelectColumns
procedure to the application, using the button on the global
extension, and mark the procedure for Export.
In your other applications (that use RunScreen) - including DLL and EXE
apps:
- Add the Global Extension template, go to the Multi DLL tab and tick
on only the first option;
This is part of a Multi-DLL program
Make sure the second option is turned off.
- Create a RunScreenSelectColumns
procedure as an External procedure exported from the Data DLL.
Integration with Other Code
A key factor in writing the class was the need for it
to play nicely with others. This section covers some common situations
where direct browse manipulation and RunScreen need to work together.
Changing a Column Heading
This should be done after the RunScreen ListManager
object initializes.
Column headings could change for one of two reasons;
a) The design time heading is a "place holder" - which will be replaced
at runtime by something more suitable. For example a Translation
template replaces the design time text with "correct" text, depending on
the language being used. The change however should be considered
"permanent" for the life of the list. In this case use;
ThisListManager1.SetListProperty(proplist:OriginalHeader,DesignTimeColumnNumber,Value)
b) The header might be changing to reflect some status or external item.
For example Paid might change to Unpaid
depending on a checkbox on the window. This change is considered
"temporary" - it might change back. In this case the code looks like
this;
ThisListManager1.SetListProperty(proplist:Header,DesignTimeColumnNumber,Value)
Hiding and Unhiding Columns
Security templates like
Secwin apply settings to browses determining what
a user can see and not see. In addition, as the user moves columns
around it's important for other code to be able to work on the "designed
column" and not go wrong just because the column has moved.
For this reason, there are four "layers" which determine what the user
can, and can't see, in the browse. These layers are applied in the
following order;
- Security - This layer is controlled by the Security mechanism your
browse is using. So, for example, Secwin operates at this level.
If a column is hidden at this level it cannot be unhidden by the
user.
- Program - This layer is controlled by code in your program. For
example, the user may have deselected a feature in your app which
causes some columns to be redundant. You can use this layer to hide
columns which are not applicable to this user.
If a column is hidden at this level it cannot be unhidden by the
user.
- User - This is the runtime choice which the user has control over,
and allows them to hide columns they are not interested in.
A user can choose to display a column which has hidden by the
programmer suggestion below.
- Programmer Suggestion (Hide by Default)
If the user has not made a selection, then these columns are hidden
from the user.
Note that the actual window design (as created by the programmer in the
window designer) is just a default, and does not inhibit any of the
layers above. In effect it acts as the default values for layer 3 (the
user layer) and can be overridden by the security, or program layers.
In order for a column to be visible it must pass the visibility test on
all four layers. In other words a column hidden by the security or
program layers cannot be unhidden by the user.
This should be done after the RunScreen ListManager object initializes.
The methods the security layer should use are
AllowColumn
and
DenyColumn.
The methods the program layer should use are
HideColumn
and
UnhideColumn.
Getting a Column Location
At design time you may know that a specific column
of interest is say column 3. At runtime you need to know the current
location of that column in order to do something with it. This is done
with the
GetColumnOrder method.
For example;
n = ThisListManager10.GetColumnOrder(3)
Examples
ABC
Shows RunScreen column formatting attached to a
Browse procedure, and also a List control on a window. Also contains an
example RunScreenSelectColumns window.
Legacy
Same as the ABC example above, but uses the Clarion
template chain rather than the ABC template chain.
Class Reference
Quick Summary
| ListManager |
| This class is applied to each browse, and provides
the runtime column ordering, locking and visibility. |
| Properties |
| Methods |
| Init |
Initialize the object. |
| Kill |
Kill the object when the window closes. |
| AllowColumn |
Used by the Security layer to
indicate that the user is allowed to see the column. |
| DenyColumn |
Used by the Security layer to
indicate that the user is not allowed to see the column. |
| DesignColumn |
Given a runtime column number identifies the design column
that is currently in that position |
| GetColumnOrder |
Given a design time column number, returns the current
position of that column. |
| HideColumn |
Used by the Program layer to
indicate that the column is not applicable to the user. |
| SettingsToString |
Converts all the current column settings to a pipe delimited
string, suitable for passing to the SelectColumns procedure, or
for saving in a table. |
| StringToSettings |
Takes a string, which was created by SettingsToString and
populates all the internal column properties with it. The string
was typically loaded from the disk, or is the result of a call
to the SelectColumns procedure. |
| UnhideColumn |
Used by the Program layer to
indicate that the column is applicable to the user, and they can
see it if desired. |
| FormatList |
Refresh the list, as a column property (or properties) have
changed. |
| SetListProperty |
Sets a property of the column of a list. |
| GetListProperty |
Gets a property of the column of a list. |
| SelectColumnsManager |
| This class is used in the RunScreenSelectColumns
procedure. The template will call all these methods, and you
should not need to call any of these methods directly. |
| Properties |
| HasToClickBox Long |
If this is true then the user has to click on the checkbox
itself to change the value. |
| Methods |
| CheckLockStatus |
Moves the lock attribute to the selected row in the list. |
| Init |
Initialize the object. |
| Kill |
Kill the object when the window closes. |
| Move |
Moves a line up or down. |
| SelectAllColumns |
Turns on, or off, the checkbox in all columns |
| SetButtons |
Enables or Disables the MoveUp and MoveDown buttons depending
on which row in the browse is highlighted. |
| SetOKButtonControl |
Enables or disables the OK button on the window. At least one
column must be set as visible for the OK button to be enabled. |
| TakeAccepted |
Handles the event:Accepted for the various buttons on the
window. |
| TakeEvent |
The main event handler. Passes event:accepted to TakeAccepted
and event:NewSelection to TakeNewSelection |
| TakeNewSelection |
Handles the Event:NewSelection when used on the List Control. |
| Trace |
A debug method that sends output to DebugView. |
Methods
Methods which you are likely to call from embed code
are described here in more detail.
AllowColumn
AllowColumn
(Long Column, [Long ToColumn], [Long Format])
Description
AllowColumn and DenyColumn are used by the
Security
layer to grant or deny access to a column or block of columns.
Parameters
| Parameter |
Description |
| Column |
The column number to allow. This is the column number as at
design time, if the column has been moved by the user that
will be handled for you. |
| ToColumn (optional) |
By using this parameter multiple columns can be set at the
same time. |
| Format (optional) |
If this parameter is true (the default) then the List
control will be reformatted immediately. If you are calling
this method multiple times together, then you can set this
parameter to false for all calls except the final one to
improve performance. |
Return Value
Nothing
See Also
DenyColumn,
HideColumn,
UnhideColumn
DenyColumn
DenyColumn (Long
Column, [Long ToColumn], [Long Format])
Description
AllowColumn and DenyColumn are used by the
Security
layer to grant or deny access to a column or block of columns.
Parameters
| Parameter |
Description |
| Column |
The column number to deny. This is the column number as at
design time, if the column has been moved by the user that
will be handled for you. |
| ToColumn (optional) |
By using this parameter multiple columns can be set at the
same time. |
| Format (optional) |
If this parameter is true (the default) then the List
control will be reformatted immediately. If you are calling
this method multiple times together, then you can set this
parameter to false for all calls except the final one to
improve performance. |
Return Value
Nothing
See Also
AllowColumn,
HideColumn,
UnhideColumn
DesignColumn
DesignColumn(Long
Column)
Description
Given a runtime column number identifies the design column that is
currently in that position.
Parameters
| Parameter |
Description |
| Column |
The runtime column number to inspect |
Return Value
The design-time column number of the column being inspected.
Example Code
x = self.control{PROPLIST:MouseDownField}
y = self.DesignColumn(x)
See Also
GetColumnOrder
GetColumnOrder
GetColumnOrder(Long
Column)
Description
Given a design-time column number returns the current position of that
column.
Parameters
| Parameter |
Description |
| Column |
The design-time column number to locate |
Return Value
The design-time column number of the column being inspected.
Example Code
The following code would be used in Clarion to set the sort order to
be on column 1.
BRW1::SortHeader.SetSortOrder(1)
Since the column 1 may be moved to another column at runtime, this
code becomes;
BRW1::SortHeader.SetSortOrder
(ThisListManager.DesignColumn(1))
See Also
DesignColumn ,
Map
GetListProperty
GetListProperty
(Long pProperty, Long pID),string
Description
Gets a property of the column of a list. Because the list's columns
change at runtime, you are no longer able to get the list column's
property(s) directly. This method translates the design time column
number with the runtime column number.
Parameters
| Parameter |
Description |
| pProperty |
The property to fetch |
| pID |
The design-time column number of the column. |
Return Value
String. The contents of the property being requested
Example Code
if
ThisListManager.GetListProperty(proplist:picture,Column) = '@d10'
See Also
SetListProperty,
FormatList
FormatList
FormatList(long
pColumn=0,long pToColumn=0)
Description
Refresh the list (or a column or specified columns), as a column
property (or properties) have changed.
Parameters
| Parameter |
Description |
| pColumn(optional) |
The column number to refresh. If omitted, refreshes the
entire list. |
| pToColumn (optional) |
The end of the column range up to which must be refreshed.
If omitted, then just pColumn is refreshed. |
Notes
If there are no columns visible after a FormatList completes then the
original format for the list is restored.
Return Value
Nothing
See Also
AllowColumn,
DenyColumn,
HideColumn
HideColumn
HideColumn (Long
Column, [Long ToColumn], [Long Format])
Description
HideColumn and UnhideColumn are used by the
Program layer to hide or unhide a column or block of columns.
Parameters
| Parameter |
Description |
| Column |
The column number to allow. This is the column number as at
design time, if the column has been moved by the user that
will be handled for you. |
| ToColumn (optional) |
By using this parameter multiple columns can be set at the
same time. |
| Format (optional) |
If this parameter is true (the default) then the List
control will be reformatted immediately. If you are calling
this method multiple times together, then you can set this
parameter to false for all calls except the final one to
improve performance. |
Return Value
Nothing
Example Code
!?MyListBox{proplist:width,Column} = 0
ThisListManager.HideColumn(Column)
See Also
AllowColumn,
DenyColumn,
UnhideColumn
Load
Load
(FileManager pTable | File pTable, Key pKeyA, *String pUserField,
<String pUser>, *String pProcedureField, String pProcedure,
*String pSettingsField)
Description
Loads (and applies) a format previously saved in the Runscreen table.
Parameters
| Parameter |
Description |
| pTable |
A FILE or FileManager object. This points to the Runscreen
table which contains the saved values. |
| pKeyA |
The primary key of the Runscreen table. |
| pUserField |
The field in the Runscreen table which contains the user
details. This is used so that different users can have
different layouts stored in the procedure. |
| pUser |
The user who is currently logged in. This value will be
assigned to pUserField in order to do the lookup on the
Runscreen table. |
| pProcedureField |
The field in the Runscreen table which contains the
procedure name. |
| pProcedure |
The name of this procedure coupled with the name of this
ListManager object. This value will be assigned to
pProcedureField in order to do the lookup on the Runscreen
table. |
| pSettingsField |
The field in the Runscreen table which contains the
settings. |
Return Value
Nothing
Example Code
ThisListManager4.Load(Access:RunScreen,
RUNS:PrimaryKey, RUNS:User, 'bruce', RUNS:Proc,
'DemoBrowse:ThisListManager4', RUNS:Settings)
See Also
Save
Map
Map(String
pList)
Description
Takes a separated list of column numbers, and returns a separated list
of current column positions. The list can be separated by a pipe ( |
), semi-colon ( ; ) or comma ( , ) character.
Parameters
| Parameter |
Description |
| pProperty |
An equate of the property to set (for the particular
column). |
Return Value
A string with a "mapped" list containing the current column positions
of the list passed in. The separator character is added to the front
and end of the list.
Example
s = ThisListManager.Map('1|2|3')
See Also
GetColumnOrder
Save
Save(FileManager
pTable | File pTable, Key pKeyA, *String pUserField, <String
pUser>, *String pProcedureField, String pProcedure, *String
pSettingsField)
Description
Saves the format of a browse, as it is, in the Runscreen table.
Parameters
| Parameter |
Description |
| pTable |
A FILE or FileManager object. This points to the Runscreen
table which contains the saved values. |
| pKeyA |
The primary key of the Runscreen table. |
| pUserField |
The field in the Runscreen table which contains the user
details. This is used so that different users can have
different layouts stored in the procedure. |
| pUser |
The user who is currently logged in. This value will be
assigned to pUserField in order to do the lookup on the
Runscreen table. If omitted then the user name is blank. |
| pProcedureField |
The field in the Runscreen table which contains the
procedure name. |
| pProcedure |
The name of this procedure coupled with the name of this
ListManager object. This value will be assigned to
pProcedureField in order to do the lookup on the Runscreen
table. |
| pSettingsField |
The field in the Runscreen table which contains the
settings. |
Return Value
Nothing
Example Code
ThisListManager4.Save(Access:RunScreen,
RUNS:PrimaryKey, RUNS:User, 'bruce', RUNS:Proc,
'DemoBrowse:ThisListManager4', RUNS:Settings)
See Also
Load
SetHeader
SetHeader(Long
pId, String pHeader, long pSetDisplayedText)
Description
Sets the header value for a specific column, to be used in the
SetColumns window. This is useful for columns in the browse that have
no header (perhaps just an icon in the column etc.)
Parameters
| Parameter |
Description |
| pID |
The (design time) column ID |
| pHeader |
The header text to use. |
| pSetDisplayedText |
If true then the current list control is updated with this
value as well. |
Return Value
Nothing
Example
ThisListManager10.SetHeader(1,'Errors',false)
See Also
SetListProperty
SetListProperty(Long
pProperty,Long pID,string pValue)
Description
Sets a property of the column of a list. Because the list's columns
change at runtime, you are no longer able to set the list column's
property(s) directly.
Parameters
| Parameter |
Description |
| pProperty |
An equate of the property to set (for the particular
column). |
| pID |
The original column number that the column was when the list
was created/populated. |
| pValue |
The value that the property must be set to. |
Return Value
Nothing
Example Code
!?MyListBox{proplist:picture,Column} = '@d10'
ThisListManager.SetListProperty(proplist:picture,Column,'@d10')
See Also
GetListProperty,
FormatList
SetUnsee
SetUnsee(Long
pIndex, Long pValue)
Description
Sets the
Unsee property. This is the
property, set by the user choice, which determines if a column is
visible or not. It is set with a method so that changes to the setting
can be detected in embed code.
Parameters
| Parameter |
Description |
| pIndex |
The (design time) column number to set. |
| pValue |
The value to set it to. |
Return Value
Nothing
See Also
UnhideColumn
UnhideColumn
(Long Column, [Long ToColumn], [Long Format])
Description
HideColumn and UnhideColumn are used by the
Program layer to hide or unhide a column or block of columns.
Parameters
| Parameter |
Description |
| Column |
The column number to allow. This is the column number as at
design time, if the column has been moved by the user that
will be handled for you. |
| ToColumn (optional) |
By using this parameter multiple columns can be set at the
same time. |
| Format (optional) |
If this parameter is true (the default) then the List
control will be reformatted immediately. If you are calling
this method multiple times together, then you can set this
parameter to false for all calls except the final one to
improve performance. |
Return Value
Nothing
Example Code
!?MyListBox{proplist:width,Column} = 0
ThisListManager.UnHideColumn(Column)
See Also
AllowColumn,
DenyColumn,
HideColumn
Frequently Asked Questions
Check out general product
CompilerErrors.
1. My text in my list column headers (or
other formatting of the list) is incorrect after adding RunScreen
This is most likely because you (or a 3rdparty product) is setting
properties of the list at runtime. You must use the ListManager methods to
set the properties of the list, and make sure you only do this after the
ThisListManager.init call in the ThisWindow.init method of your procedure.
See
rsGetProperty,
rsSetProperty,
HideColumn and
UnhideColumn
for details.
2. After upgrading I am getting errors in my code around
GetProperty and SetProperty method calls.
These properties have been renamed to
rsGetProperty
and
rsSetProperty respectively. Just
change the name of the method called in your code.
Support
Your questions, comments and suggestions are welcome.
See our web page (
capesoft.com) for new
versions. You can also contact us in one of the following ways:
| CapeSoft Support |
| Email |
 |
| Telephone |
+27 (087) 828 0123 |
Installation
Run the supplied installation file.
Distribution
This product is supplied as source files that are
included in your application. There are no additional files for you to add
to your distribution.
License and Copyright
This template is copyright © 2024 by CapeSoft
Software. None of the included files may be distributed. Your programs
which use this product can be distributed without any royalties due on
this product.
Each developer needs his own license to use this product. (Need to
buy more licenses?)
This product is provided as-is. CapeSoft Software and CapeSoft Electronics
(collectively trading as CapeSoft), their employees and dealers explicitly
accept no liability for any loss or damages which may occur from using
this package. Use of this package constitutes agreement with this license.
This package is used entirely at your own risk.
Use of this product implies your acceptance of this, along with the
recognition of the copyright stated above. In no way will CapeSoft , their
employees or affiliates be liable in any way for any damages or business
losses you may incur as a direct or indirect result of using this product.
For the full EULA see
https://capesoft.com/eula.htmlHow to use List Box Management Already Built in to
ABC
RunScreen offers you Browse Column Management, but
Clarion already does this in the box. So before choosing RunScreen over
that it's worth trying out the one you already have. This section is a
quick-start guide to doing that.
- Go to the Application Global Properties, to the App Settings Tab
- Tick on the option Enable List Format Manager
- If you like you can click on the List Format Manager Configuration
button, but the defaults work fine.
- Run your program (no local settings are necessary), go to any
browse, Right-click anywhere on the browse and choose List Formats.
The program lets you select from a list of save formats, or create a
new format. (Formats apply on a browse-by-browse basis)
There are local settings you can explore for each browse (See Browse
Extension, Extended Options Tab) and these are covered in the Clarion Help
quite well, so that's well worth a read.
Version History
Version 1.33 (2 April 2024)
- Fix: Legacy Load and Save could fail if Table was already open.
Version 1.32 (9 March 2024)
Version 1.31 (14 June 2023)
- Add: WebHandlerRunScreen procedure Extension template. For NetTalk
14 WebHandler. Saves user column sizing between sessions.
- Add: ListManagerWeb class (For NetTalk 14)
- Fix: Virtual attribute added to Load and Save methods.
Version 1.30 (8 December 2022)
- Fix: Change in 1.29 could cause an Index Out of Range error.
Version 1.29 (29 August 2022)
- Fix: Locking Columns did not like lock on column after column that
had been moved.
Version 1.28 (15 July 2022)
- Embed point added between loading of settings, and call to
FormatList.
- Fix: Removed clearing of deny and hide in readcontrol method.
Version 1.27 (25 May 2021)
Version 1.26 (20 May 2020)
- Add: Support for Secwin 7
- Various protections for Index-out-of-range errors.
Version 1.25 (14 September 2018)
- Add: Clarion 11 to install.
Version 1.24 (6 March 2018)
- Fix: Compile error if Save Settings were set to Table, but no Table
was set.
- Fix: (Regression) Moved FormatList call in template inside check,
closer to StringToSettings.
Version 1.23 (18 January 2018)
- Fix: Regression: Auto RunScreen settings were not automatically
applied after a call to Load.
Version 1.22 (20 December 2017)
- Add: Hide by Default template
settings.
- Fix: If Save in Table global setting was off, but a table was set,
the the Load/Save still happened.
Version 1.21 (14 December 2017)
- Add: SetUnsee method
- Change: When doing a FormatList, if no
columns are visible after the format, then the list resets to Original
state. (Courtesy Francisco Duran)
Version 1.20 (20 April 2017)
- Fix: Regression in 1.19 which sets selected row based on mouse-down.
Version 1.19 (20 April 2017)
- Add: Map method.
- Fix: Local Auto RunScreen template did not call SetFamily.
Version 1.18 (25 February 2017)
- Add: OriginalHeader, DisableDragAndDrop, IgnoreNewSelection,
DontSaveRecord properties.
- Change: New parameter to SetHeader method
Version 1.17 (26 January 2017)
- Fix: GetColumnWidth was being called by ReadControl before self.columns
was set. Resulted in strange effects in groups.
Version 1.17 (18 October 2016)
- Change: SetProperty method renamed
to SetListProperty. GetProperty method
renamed to GetListProperty. (Works around Compiler bug with methods
named SetProperty and GetProperty.) -
Version 1.16 (1 June 2016)
- Add: New Method, GetColumnWidth
- Fix: The width of the last column in a group was not remembered.
- Internal Refactor: OMITTED statements no longer use numeric values.
Version 1.15 (7 Jan 2016)
- Fix: If a quote was used in a column's header text then the
SetColumns window would not appear. (thanks to Sean Hennessy)
- Add: If the EVALUATE command fails when calling SetColumns, the the
error, and command, are sent to Debugview.
Version 1.14 (2 April 2015)
- Fix: Some use of .Value still in the template.
Version 1.13 (25 February 2015)
- Install contains support for Clarion 10
Version 1.11 (3 November 2014)
- Save method will not actually do a save if no columns are visible.
Version 1.10 (19 June 2014)
- Default control ID added for some of the buttons in 1.09 were wrong.
- Fix: If the browse had a locked column,. and the lock was removed,
it could remember the previous setting.
- Fix: Prevent potential endless loop in .Save method.
- Add: Calls to ErrorTrap if the disk access fails in the .Save
method.
Version 1.09 (4 June 2014)
- Fix for template errors when saving to a table.
- Fix: Control test in SelectColumns procedure template made case
insensitive
- Fix: "Disable Runscreen" did not completely eliminate code from all
templates.
- Fix: Replaced GetValue in calls to INI manager with GetValuePtr
- Fix: Default values set for control equates on runstime screen in
case the controls are not detected.
Version 1.08 (2 April 2014)
- Compatible release with StringTheory 2 (fix for use with the
inimanager ABC class).
Version 1.07 (17 March 2014) (Requires StringTheory
2.00 or more recent)
- Compatible release with StringTheory 2
Version 1.06 (27 January 2014)
- Clarion 9.1 build
- Add: Multi-DLL Examples
- AutoRunScreen template clashed with GUTS template.
- Better integration with AnyText accessory.
- Fixed: ChangeColumnOrder method. Was not catering for hidden columns
when moving columns around.
- Fix: Template clash with RecentLookups Saving field entries.
Template prompts (probably a C9 bug) were bleeding through to
RunScreen local instance.
Version 1.05 (16 October 2013)
- Add: ResetToOriginal() method - can be called to reset the browse
format to the original design. (An alternative to opening the Select
Columns window, and selecting "Reset")
Version 1.04 (4 September 2013)
- Add: Second Global Extension "Activate Auto RunScreen". You can now
choose to add to browses/lists individually, or for the whole
application in one go.
- Disabled: Drag and Drop support for the columns in Clarion 9 is
problematic because of the way events on a list now work. This
function has been disabled for now.
- Fix: Template generated class even if RunScreen was disabled.
Version 1.03 (7 August 2013)
- Refinement: If ChangeColumnProcs is not set then a comment is
generated on the line with the compile error.
Version 1.03 (7 August 2013)
- Change (Internal): Parameter order in GetProperty and SetProperty
reversed.
- Check: If control=0 passed to Init method then throws an error to
ErrorTrap
- Fix: On event:NewSelection, Choice only updated for MouseLeft
keycodes. Fixes problem with arrow keys in list box.
- Fix: Keycode cleared after mouseLeft processing (fixes problem with
VCR controls on list box).
- Fix: If the left-most column is a browse was hidden, it could only
be unhidden with a reset.
- Fix: Global template not happy with table name (for save) being
default. Lookup is necessary.
- Fix: Added MULTI attribute to browse extension, allows extension to
be added to multiple browses _on the same table_.
- Tweak: RuntimeSelectColumns procedure, return value (ans) set before
the SelectColumnsManager object is KILLed.
- Fix: Example shipped with invalid TPS files
- Fix: Example contained a list format in the browse which did not
convert well to C8.
Version 1.02 (30 July 2013)
- Fix: TXA and TXD files were missing from the install.
- Fix: Supplier.Tps example file was corrupt.
Version 1.01 (26 July 2013)
Version 1.00
