Documentation
Download Latest Version Index JumpStart FAQ Templates Classes History
CapeSoft Logo

CapeSoft RunScreen
Documentation

Installed Version Latest Version

Introduction

Please Note: RunScreen requires StringTheory

RunScreen allows the user to control certain elements of your program at runtime. Specifically;

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;  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.
  1. Global Properties
  2. Classes Tab
  3. Enable Use of ABC Classes ON

Column Management - Single App system (ABC or Legacy)

  1. If you have the ABC List Format Manager currently on, then turn that off on the Global Properties for the app, App Settings tab.
  2. Add the Activate StringTheory Global Extension to the application.
  3. Add the Activate RunScreen Global Extension to the application.
     
    1. Click on the Import SelectColumns Procedure button
  4. Add the Activate Auto RunScreen Global Extension

    OR
  5. (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.
  6. (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

  1. Apply the instructions for a Single app system (Steps 1 through 4) to this DLL.
  2. In addition, make sure both options on the Multi-DLL tab are on.
  3. Mark the imported RunScreenSelectColumns procedure as Export.

Other DLLs and EXE(s)

  1. 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).
  2. Add the StringTheory, RunScreen  and Activate Auto RunScreen Global Extensions but DO NOT click on the Import SelectColumns Procedure button.
  3. 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

If you have hand code to set various list column properties (like proplist:picture), then you need to change this to effect the correct columns. See rsGetProperty, rsSetProperty, HideColumn and UnhideColumn

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; The column formatter allows you to;

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;
 
  1. Design the column in the Window formatter as you want it to appear when it is visible. ie set the appropriate width etc.
  2. 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

  1. 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.
  2. 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.
  3. 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 3 step process;
  1. 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.
  2. Click the Refresh Classes button. Then click the Classes button. You should see your new derived class listed there.
  3. In the ListManager Class Name field select the name of your derived class. In this case CustomListManager.
  4. 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.
App ID Prefix
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.
ListManager Class Name
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: In your other applications (that use RunScreen) - including DLL and EXE apps:

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;
  1. 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.
  2. 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.
  3. 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.
  4. 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.
rsSetProperty Sets a property of the column of a list.
rsGetProperty 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)
! y now contains the design-time column number clicked on.

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

rsGetProperty (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 ?MyListBox{proplist:picture,Column} = '@d10'     !old code
if ThisListManager.GetListProperty(proplist:picture,Column) = '@d10'   !New code

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     !old code
ThisListManager.HideColumn(Column)        
!New code

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') ! s now contains something like '|4|2|9'
 
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'     !old code
ThisListManager.SetListProperty(proplist:picture,Column,'@d10')   !New code

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     !old code
ThisListManager.UnHideColumn(Column)      
!New code

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.html

How 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.
  1. Go to the Application Global Properties, to the App Settings Tab
  2. Tick on the option Enable List Format Manager
  3. If you like you can click on the List Format Manager Configuration button, but the defaults work fine.
  4. 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.32 (9 March 2024) Version 1.31 (14 June 2023) Version 1.30 (8 December 2022) Version 1.29 (29 August 2022) Version 1.28 (15 July 2022) Version 1.27 (25 May 2021) Version 1.26 (20 May 2020) Version 1.25 (14 September 2018) Version 1.24 (6 March 2018) Version 1.23 (18 January 2018) Version 1.22 (20 December 2017) Version 1.21 (14 December 2017) Version 1.20 (20 April 2017) Version 1.19 (20 April 2017) Version 1.18 (25 February 2017) Version 1.17 (26 January 2017) Version 1.17 (18 October 2016) Version 1.16 (1 June 2016) Version 1.15 (7 Jan 2016) Version 1.14 (2 April 2015) Version 1.13 (25 February 2015) Version 1.11 (3 November 2014) Version 1.10 (19 June 2014) 
Version 1.09 (4 June 2014) 
Version 1.08 (2 April 2014)  Version 1.07 (17 March 2014)  (Requires StringTheory 2.00 or more recent) Version 1.06 (27 January 2014) Version 1.05 (16 October 2013) Version 1.04 (4 September 2013) Version 1.03 (7 August 2013) Version 1.03 (7 August 2013) Version 1.02 (30 July 2013) Version 1.01 (26 July 2013) Version 1.00