CapeSoft.Com
Clarion Accessories
RecentLookups
Documentation
Download Latest Version Index JumpStart FAQ History Templates Classes
CapeSoft Logo

CapeSoft RecentLookups
Documentation

Installed Version Latest Version

Introduction

Lookups are one of the features common to pretty much any Clarion application. They have been in our applications since the days of Clarion for DOS. Most lookup controls though are very feature-poor, forcing the user to use out-dated techniques to look up related records.

The goal of RecentLookups is to make looking up a related record as simple, and as powerful, as it can possibly be.

Features

Jump Start

Recent Lookups contains a number of different functionalities, which can be added to your application independently of each other. In other words you may choose to implement all the functionalities, or just some of them This section explains briefly how to get the functionality into your application.

1. Import Into Dictionary

Open your application dictionary, and import the file RecentLookups.Txd. This TXD file is located in your Clarion9\accessory\libsrc\win folder. This should add a table called RecentLookups to your application. You are welcome to adapt the table to your application, for example by changing the File Driver, if you wish to do so. You may also need to change the sizes of some fields if your file driver has key-length limits. For a longer discussion on changing the table see the section entitled RecentLookups Table.

2. Add Global Extension

Add the Recent Lookups Global Extension to your application.

Set the following settings on the Global Extension; If you have a Multi-DLL system then add the global extension, to each of the apps.

Once you have done the two mandatory steps above, then you can do one or more of the following optional steps;

3. Configure Lookup Browses

Adding the global extension automatically adds the Recent Selections functionality to any browse which has a Select button. To get the most out of the functionality though, the following changes to the browse are recommended;
  1. Using the List Box Formatter, set the STYLE attribute on for the Header Field in the list control. Or better yet;
  2. (Recommended) Set the STYLE attribute on for all the columns in the list control.
  3. (Optional) On the RecentSelections Extension set the Header Field to the field you wish to contain the ALL and RECENT headers. This will default to the first String field in the List. (If you override the template, then you must also select a column which is a String.)

4. Replace Lookup Controls on Forms

To make use of the advanced Lookup control you need to replace the lookup fields on the Form. (This has nothing to do with the Recent Selections functionality - you get that regardless of whether you do this step or not. To replace a lookup control with a RecentLookups Lookup control, follow these steps;
  1. Open the form in the Window Formatter, and identify the field that can be populated via a lookup.
  2. Make a note of the variable the field is using.
  3. Delete the Entry field from the window. (Leave the prompt field alone.) If the field has a Lookup button, or description string field then remove those as well.
  4. From the Control Templates pad, select the RecentLookupControl and place it on the form where the deleted field used to be.
  5. Position and set the size of the control appropriately. Remember this will show the description, not the value, so may need to be wider than the control you had there before. You do not need to allow space for the Drop or Lookup buttons, these will be added inside the space you allocate to the Entry control.
  6. Right-Click on the control, and select Actions to see the template prompts for the control. (You will also find these prompts on the Procedure Extension list.) Fill out the field settings appropriately (For more on what each field means, see the section  Lookup Control Template.
   

RecentLookups Table

The information RecentLookups needs is stored in a table called RecentLookups. This table needs to be imported into your dictionary by importing the RecentLookups.TXD file.This TXD file is located in your Clarion9\accessory\libsrc\win folder.

The table contains a number of fields, but you are able to make changes to the table if you need to do so. Here are some of the changes you are most likely to make;
  1. Change the file driver to match the rest of your application.
  2. Set the Owner Name property to match other tables in your application - especially for SQL tables.
  3. Reduce the size of the User and Table fields to accommodate key-length or record-length restrictions imposed by your file driver of choice. The User field should be large enough to contain your application's User ID value, and the Table field should be long enough to contain your largest table name.
  4. You can reduce the number of KeyFields to match the maximum number of key fields that your dictionary has in a primary key. Typically developers have no more than 2 or 3 fields in a primary key, but RecentLookups supports up to 10 fields in a primary key. If you remove fields from the table, then you will need to remove fields from the key KeyFields as well.
  5. You can reduce the size of each Keyfield as well. They default to very large strings, and most developers use much shorter fields in their Primary Keys. To accommodate LONG values, a minimum string length of 10 is required.
Note that while changing the name of fields is permissible, changing the DATA TYPE of fields is not allowed.

Browses Used for Lookups

The Recent Selections extension template is automatically added to any browse which has a Select button. When the browse is in Select mode, then the extension is active.

The requirements for this to work on a browse are pretty straight-forward, however there are a few things you can do to make the browses look even better when being used as a Lookup.
First the Requirements;
  1. One of the fields on the browse must be a String field. Ideally this field should be in the first, or second column of the browse.
  2. This field must have the STYLE attribute turned on.
Now some of the suggestions;
  1. Turn on the STYLE attribute for all columns in the browse

Templates

Global Template

General Tab

Disable All Recent Lookup Features
This disables the Recent Lookup template, and no template code will be generated into the application. This is useful for debugging.

Saving Tab

Table
The RecentLookups table in the dictionary.
Fields Key
The key which contains the following fields; Favorite, User, Table and Keyfields.
Time Key
The key containing Favorite, User, Table, Date and Time fields.
ID Field
A unique ID string field for the table - acts as the unique row identifier (primary key) for the table.
Favorite Field
Reserved for future use.
User Field
A string containing the user ID field for your application. This allows different users to have different recent values selected for each table.
Table Field
A string to contain the name of the table the lookup was done on.
Date Field
The Date field, stored as a LONG, in the table.
Time Field
The Time field, stored as a LONG, in the table.
Key Field 1 ... Key Field 10
Up to 10 key fields, which means support for up to 10 components in a lookup key.

Options Tab

Use Secwin User
If you are using Secwin in this program, then tick this option on to automatically associate the lookup history with the currently logged in Secwin user.
Use Super Security User
If you are using Super Security (from BoxSoft) in this program, then tick this option on to automatically associate the lookup history with the currently logged in Super Security user.
Logged In User
If you are not using Secwin then enter an expression here to identify the current user.
Activate RecentLookups on
Set this to "All browses with a Select button" to automatically enable the functionality on all browses with a Support button. You can override this setting at the local template level.
Include Section Headers
Tick this option on to include Section Headers on lookups where recent selections exist. This adds a line for RECENT and another line for ALL.
Drop List Height
Sets the number of rows visible when a drop-list is activated on an Entry field. The default is 5 rows. This setting is used for all lookup fields, which do not have a specific drop list value of their own.

Styles Tab

Headers
Set the style, which will be applied to the list control, for the ALL and RECENT header lines.
Recents
Set the style which will be applied to all Recent values added to the lookup. This can be useful to differentiate the recent values from the normal values, if the headers are not used.

Drop Button Tab

Icon
Specify the icon to use on the drop button. This defaults to tDown.ico, but you can use any other icon that you prefer. Leave this field blank if you prefer to use text on the button rather than an icon.
Text
Instead of an icon you can place text on the button. Typically a single character as the button is very small. This can be useful though if you are using a pictoral font, like WingDings.
Font Name
If you are using text, then enter the Font name here, if it is not the default font for the window.
Flat
Tick this on to set the FLAT attribute on the button.
Background Color
If the FLAT attribute is not set, then you can set the background color for the button here.

Lookup Button Tab

Hotkey
The hotkey which when pressed on the entry field will automatically trigger the lookup. This defaults to the F2 Key (113). This is in addition to the ? key which which also acts as a hot key for the lookup.

The other settings on this tab are the same as for Drop Button (see above), but applied to the Lookup button.

Auto Complete Tab

Chars before auto-complete
The number of characters which are typed before the automatic auto-complete list appears.

Translate Tab

All
Used to indicate the ALL section in a lookup.
Recent
Used to indicate the RECENT section in a lookup.
Edit Warning
This warning will appear if the user attempts to call a form for a Recent item. recent items cannot be edited, the user must edit from the ALL section of the lookup, if indeed Editing is available at all from the lookup.

Multi-DLL Tab

This is part of a Multi-DLL Program
Tick this on if this application is a DLL or EXE which is part of a multi-app suite of apps.
Export Recent Classes from this DLL
Tick this on only if this is the data dll in the suite of apps.

Classes Tab

Class Version
An internal version number.

Recent Browse Template

General Tab

Enable This Template
Set this to one of Default (ie the global setting will be used) or Yes, or No to override the global setting.
Header Field
Lets you select which field in the list control will be the designated Header column, used for the ALL and RECENT headers.

Options Tab

Use View
Reserved for future use.

Class Tab

Object Name
The name of the object which will be generated.
Class Name
the class to use for the object. Defaults to SelectRecentManager.

Recent List Template

General Tab

Enable This Template
Set this to one of Default (ie the global setting will be used) or Yes, or No to override the global setting.
Control
The list control to attach this template to.
Queue
The Queue which is used to populate the selected list control.
Header Field
Lets you select which field in the list control will be the designated Header column, used for the ALL and RECENT headers.

Options Tab

Class Tab

Object Name
The name of the object which will be generated.
Class Name
the class to use for the object. Defaults to SelectRecentManager.

Lookup Control Template

Options Tab

Disable this template
Turn this on to not generate any code for this control template. This can be useful for debugging purposes.
Table
Select the remote table here. This is the table the user will be selecting from.
Desc Key
Enter the Description key for the remote table here. This field is optional, however having a key on the description field(s) in the remote table will improve the functionality of the control.
Id Key
Enter the remote table's ID Key here. This is usually the primary key of the remote table.
Linking Fields
Match up any unmatched fields here. Typically each item in the remote table's ID key appears in this list, and must be matched to a field in the local table.
More Assignments
If you are fetching data from the remote table, that is not in the primary key, then add those assignments here.
Show Lookup if Entry invalid
If this options is on and the user enters an incorrect value, and the field did not contain a correct value before, then the Lookup window is automatically displayed.
Allow Invalid Entries
If this option is on and the user types a value into the field, which is not located in the lookup, then accept the value as correct.
Allow Blank Entries
If this option is on, and the user clears a field, then allow the field to remain cleared. This allows the field to be either a valid value, or blank.
Call Reset After Lookup
If this is on then the Reset method (ABC) or RefreshWindow routine (Legacy) will be called when the contents of the lookup field changes. This is useful for fields which are acting as filters for other fields on the window, like browses.
Validate Invalid Code
This button goes to an embed point. When the user enters an invalid value a method (AskAllowInvalid) will be called. By default this method returns true. However you can enter embed code here to validate the entered value. You can then return False to reject the value. This allows invalid codes to be entered, but only if the code conforms to some specification.

Lookup Tab

Activate Lookup
Turn this on to include a lookup button, and functionality with the control.
Lookup Procedure
Select the name of a Lookup Procedure here. When the user clicks the lookup button, then this procedure will be called, using normal Clarion lookup calls. This lookup can have, but does not have to have, the Recent Browse Extension added to it.
Parameters
Optionally enter any additional parameters that the procedure may need here.
Return Variable
Optionally enter a variable here to accept a value returned by the Lookup Procedure.

Auto Complete Tab

Activate Auto-Complete
Tick this on to activate Auto-Complete functionality on the entry field.
Chars before auto
The number of characters to type before the auto-complete search is done.
Order (csl)
The default sort order for the auto-complete results is the Description fields. If you wish to customize the sort order, then enter it here as a comma separated list.
Filter
If you wish to apply an additional filter to the auto-complete selection, then enter the filter here.
Filter is an Expression
Turn this option on if the filter contains an expression rather than a constant string value.
Display
By default the description fields will be displayed in the drop down. If you wish to customize the fields displayed in the drop list then enter an expression here.
Search Type
The auto-complete can search using a CONTAINS search or a BEGINS-WITH search. Choose the one appropriate to your situation. The default is CONTAINS.
Send Filter to Debugview
If this option is on then the filter created during the auto-complete will be sent to Debugview for debugging purposes.
Additional Search Fields
By default the search (for the letters the user has already typed) spans across all the code, and description fields. If you want the search to apply to other fields in the remote table as well, then enter them here.
Maximum Options
The maximum number of items to read from the table to display in the auto-complete list. The default vlaue is 100. The higher this value the longer it can take to read the possible options.
Drop List Height
Sets the number of rows to display when the drop-down button is pressed. If left blank then the global default value is used.
Min Drop List Width
If left blank the width of the Entry control is used to set the drop list width. However if you want the drop list have a minimu width, and hence be wider then the entry field then you can enter an expression here. If the entry is wider than this expression then the entry width will be used for the drop list, otherwise the value entered here will be used.

ViewFields Tab

Remote View Field
A VIEW structure is generated to populate the Auto-Complete list. If you are using fields in code, or in the DISPLAY setting, other than the ID and Description fields, then enter those fields here.

Class Tab

Object Name
The name of the object. Defaults this ThisLookupX where X is a number.
Class Name
The name of the class that the object is instantiated from. the default class is LookupManager.

Using in a Multi-DLL System

In your Data-DLL: In your other applications (that use RecentLookups) - including DLL and EXE apps:

Example

There are a number of examples that ship with RecentLookups;
  1. ABC
    An example of using RecentLookups in a single ABC Template based EXE program
  2. Legacy
    An example of using RecentLookups in a single Clarion Template based EXE program
  3. MultiDLLABC
    An example of using RecentLookups in an ABC program, comprising of a Data DLL, an EXE and other DLL's.
  4. MultiDLLLegacy
    An example of using RecentLookups in a Clarion Template program, comprising of a Data DLL, an EXE and other DLL's.

Embed Code

This section shows specific embed code that you might want to use in specific situations.

Updating the contents of the lookup control when the ID field changes

When a form opens the lookup controls are automatically synchronized with the child tables. In other words the child records are loaded and the necessary description fields are placed in the entry control. If you change the underlying ID in code though you want the description to change as well. This is accomplished with the following line of embed code;

Inv:CustomerId = 'newId'   ! This is your line of code to change the ID
ThisLookup1.LocalChanged() ! This is the line you add to update the lookup control

another example;

Access:Invoices.Fetch(somekey) ! a new record has been loaded
ThisLookup1.LocalChanged()     ! this is the line you add to update the control

Controlling the Description field in the Lookup Field

When using the lookup control, a description field (or fields) are displayed instead of the "code" field. This is desirable because this makes for a much more intuitive interface for the user to use. In most cases you simply enter a "description key" for the lookup table, and the fields from that key are used by the class and everything just works.

In some cases however the description field is not in the lookup table at all, and thus no description key exists. You can of course simply leave the key setting blank and the code field will be used instead. Alternatively you can use embed code to control the relationship between the code field, and the description you wish to display. This section in the document explains the requirements for your code.

In order to use your own description fields, it is a good idea to set the Desc Key field for the control to nothing.


RemoteFileLinks

The next step is to embed code to identify the fields you will use. This is done in the RemoteFileLinks method in your procedure. Note that if you have multiple lookup fields on the window you will want to make sure you are embedding into the correct method, so check the Class tab for the correct name.

The code you will add will come after the Parent call in this method.
There are two distinct properties to set here, and each is an Array, so there are also two "counter" properties to add.

The first property to set is an array called RemoteDesc. You are allowed up to 5 of these for one entry field. This property determines the text which will be visible to the user in the display field. These are assigned using a &= operator. The DescFields is set to indicate how many of the array fields are used. For example;

self.RemoteDesc[1] &= inv:date
self.RemoteDesc[2] &= cus:name
self.DescFields = 2

The second property to set is called RemoteDescName. This is used when creating the filter for auto-complete. It is used to best match what the user is typing. The fields used here need to be in the tables used by the View [1]. As before there is a property containing the number of fields used. This property is called DescNameFields.  If the auto-complete feature is turned off, or suggesting auto-complete options via the description is not practical, then you can just set DescNameFields to 0. For example;

Self.RemoteDescName[1] = 'inv:date'
Self.DescNameFields = 1

[1] A view is generated into the LoadSuggestions method, and is used to populate the auto-complete lookup list. You can add additional tables to the View if you wish by embedding JOIN commands.

GetEntryDescription

By default the description field displayed to the end user is a space separated list of the RemoteDesc fields. Should you wish to alter this description then you can do so in the GetEntryDescription method. For example, to replace the space separator with a / separator you might have code as follows;

Return clip(Self.RemoteDesc[1]) & '/' & clip(Self.RemoteDesc[2]))

LoadRemoteRecordId

When the record ID changes, the description field needs to be updated. This is done in the LoadRemoteRecordId method, after the parent call. At this point the remote record is loaded (if the parent call was successful.) Your code in here should do whatever it needs to do to load the description based on that value.

For example, given a remote table SAL, and a unrelated table USR (which you now need to load) you might have something like;

  If ReturnValue = 0                 ! remote record load was successful
    USR:SysIdUser = Sal:SysIdUser
    If Access:UserFile.TryFetch(USR:PK_User) = Level:Benign
      Self.RemoteFound = true        !   desc record loaded ok
    End
  End 

LoadRemoteRecordDesc

If the user types an entry in the lookup field and moves on to a new field then a lookup is done to find the record that the user is specifying. This is done in the LoadRemoteRecordDesc method. Since the template setting Desk Key is blank this method does nothing and simply returns -1.

If this facility is possible, using the alternate description, then you can add your own embed code to find the appropriate lookup record here. Your code should do the following things in order to indicate success;
  1. load the lookup table record with the correct record.
  2. set the self.RemoteFound property to true
  3. Return 0
For example;

  !Self.RemoteDesc[1] has been set which in this case is USR:Username .
  !   need to load both the supplemental file and the remote file

  If Access:UserFile.Fetch(USR:SK_User_UserName) = level:benign
    Sal:SysIdUser = USR:SysIdUser
    If Access:SalesPerson.Fetch(Sal:FK_SalesPerson_User) = level:benign
      Return 0
    End
  End
  ! if the above failed, then fall back on the remote file code as normal.
  ReturnValue = PARENT.LoadRemoteRecordDesc ()
  Return ReturnValue

If it is not possible for the user to type an entry which can be matched to the record they are looking for (perhaps because the description field is not unique), then you can choose not to embed any code in this method and this feature will not exist. (It is still possible for the user to type the code field.)

Class Reference

RecentBase

The RecentBase class is an internal class which covers functionality common to the other classes. It covers mostly debugging and logging functionality.

Properties

Property Type Description
LoggingOn Long If this property is set to 1, then calls to the LOG method are automatically passed on to the TRACE method, and hence output to DebugView.
Proc String The name of the procedure which owns the object.
SuppressErrors Long If this error is true, then calls to the ERRORTRAP method will not generate a MESSAGE to the user. If this is false then Errors are displayed to the user as a MESSAGE statement.

Methods

DebugEvent

DebugEvent (string pExtra)

Description

Sends a string version of the current event, along with the current field() and keycode() values to the trace method. The contents of the extra parameter are passed to the trace method as well. Typically called from a TakeEvent method to help debug the sequence of events.

Parameters

Parameter Description
pExtra String Additional information to include in the call to trace.

Return Value

none

See Also

Trace

ErrorTrap

ErrorTrap (string pProc, string pStr)

Description

Displays a message to the user when some unexpected error occurred. These messages can be suppressed by setting the SuppressErrors property to true. The message is also passed on to the Log method.

Parameters

Parameter Description
pProc String The name of the method that made the call.
pStr String The Message to display to the user (if the SuppressErrors property is 0)

Return Value

none

See Also

Log

InterpretEvent

InterpretEvent ([long pEvent])

Description

Converts an event code into an English description of the event. Used by the DebugEvent method to translate event codes into Event descriptions.

Parameters

Parameter Description
pEvent Long (optional) The event to interpret. If omitted then the current Event() value is used.

Return Value

none

See Also

DebugEvent

Log

Log (string pStr)

Description

Sends the pStr value to the Trace method, but only if the LoggingOn property is true.

Parameters

Parameter Description
pStr String The string to add to the log

Return Value

none

See Also

Trace

Trace

Trace (string pStr)

Description

Sends a string to standard windows debugging output (like DebugView.Exe). Includes the tag [rec] the thread number and the procedure name.

Parameters

Parameter Description
pStr String The string to send to Debugview.

Return Value

none

See Also

Log

LookupManager

The LookupManager is derived from the RecentBase class, so all those methods and properties apply here as well.

Properties

Property Type Description
AsAtText STRING Last known contents of the entry control.
AutoComplete LONG Set to true if the Auto Complete functionality is active.
AutoCompleteLen LONG Number of characters to type before auto-complete automatically displays the options. Default is 2.
AutoLookupWhenEntryInvalid LONG If set to true, and the user types an invalid entry, then the Lookup browse automatically appears.
DescFields LONG Number of description fields in the remote table.
DropButton LONG FEQ of the Drop button
EntryControl LONG FEQ of the entry control
EntryText STRING Current contents of the entry control.
HotKey LONG Keycode of the HotKey used to Trigger a Lookup. F2Key by default.
LinkedFields LONG Number of id fields in the link between the local table and the remote table.
ListControl LONG FEQ of the List Control
LocalId ANY,Dim(MaxLinkFields) Array of pointers to the id fields in the local table.
Lookup LONG Set to true if the Lookup functionality is active.
LookupButton LONG FEQ of the Lookup Button
LookupResult LONG Value returned from the lookup procedure.
RemoteDesc ANY,Dim(MaxDescFields) Array of pointers to the fields in the description key of the remote table.
RemoteDescKey &KEY Pointer the the description key in the remote table.
RemoteDescName String,Dim(MaxDescFields) Names of all the fields in the remote table description key.
RemoteFile &FILE File pointer to the remote file structure.
RemoteId ANY,Dim(MaxLinkFields) Array of pointers to the id fields in the remote table.
RemoteIdKey &KEY Pointer to the ID key in the remote table.
RemoteIdName ANY,Dim(MaxLinkFields) Names of all the fields in the remote table ID key.
Suggestions &SuggestionsQueueType The queue used for the List Control. Contains the auto-complete suggestions.
SuggestionsQueueType    
Display STRING Text displayed in the List Control as an auto-complete suggestion.
DisplayStyle LONG The style number used for the List Control
SuggestionID STRING,Dim(MaxLinkFields) The ID value(s) for the record.
SuggestionDesc STRING,Dim(MaxDescFields) The Description value(s) for the record.

Methods

Method Description
AfterChange Called after the entry field is changed, via either a Lookup or the user typing something.
AfterEntry Called when the entry field has been changed by the user typing something into the field.
AfterLookup Called when the user returns from a lookup window.
AskAllowInvalid Allows the user to add code to determine if an entered field is valid or not.
CheckFilter Checks the filter set by SetFilter when the user enters a code, or description, directly.
ClearField Clear the entry field. (Same as the Clear button.)
Disable Disable the field (and related fields) on the window.
DisableUnderneath Disables fields under the list control.
Drop Open the Drop list (Same as the Drop button.)
Enable Enable the field (and related fields) on the window.
EnableUnderneath Enables fields previously disabled with DisableUnderneath.
GetEntryDescription Returns the description as a single string.
Hide Hide the field (and related fields) on the window.
HideSuggestions Hides the drop-down list.
Init Initializes the object and sets various properties to match desired behaviors.
LocalChanged Loads the foreign record if the contents of the lookup field has changed.
LoadSuggestions A method that loads suggestions into the drop-list, as the user types.
MakeFilter Makes the filter for the VIEW as the user types.
ReadOnly Sets the entry field as read-only.
Refresh Refreshes the state, and position of the various controls, with respect to the entry control.
SetFilter Sets the filter for records that can be entered directly into the Entry control.
SetListPosition Sets the position of the list control
ShowSuggestions Shows suggestions to the user (as a drop-down list) as they are typing.
Unhide Unhide the field (and related fields) on the window.

AfterChange

AfterChange()

Description

Called after the entry field is changed, via either a Lookup or the user typing something. Used by the template to embed additional assignments and so on.

Parameters

none

Return Value

none

See Also

AfterEntry, AfterLookup

AfterEntry

AfterEntry()

Description

Called when the entry field has been changed by the user typing something into the field.

Parameters

none
Return Value

none

See Also

AfterChange, AfterLookup

AfterLookup

AfterLookup()

Description

Called when the user returns from a lookup window.

Parameters

none

Return Value

none

See Also

AfterChange, AfterEntry

AskAllowInvalid

AskAllowInvalid (String pInvalidText)

Description

This method is called to allow the program to insert the invalid record (or conditionally insert it). You can also use this method to lookup a valid value from another table (maybe a linking table) and then set the valid value.

Parameters

Parameter Description
pInvalidText The text the user has entered

Return Value

True or False. If true then the entered text is acceptable, if false then the entered text is not acceptable. If no derived code is in the program then the default method returns false.

See Also



CheckFilter

CheckFilter()

Description

Evaluates the filter set by the SetFilter method.

Parameters

none

Return Value

0 if the record is successful, non-zero if it is not successful.

notes

This method is called when a user enters an ID or Description directly into the entry field. It will only be called if a record matching the ID or Description is found. Only the lookup record is loaded at this point. Therefore if the filter contains additional records then those need to be loaded manually (most likely in the CheckFilter method, before the parent call).

See Also

SetFilter

ClearField

ClearField()

Description

Clear the entry field. (Only does anything if the AllowBlank property is set.) Same as clicking on the Clear button (X) on the entry control.

Parameters

none

Return Value

none

See Also

Hide, Disable, ReadOnly

Disable

Disable()

Description

Disable the field (and related fields) on the window.

Parameters

none

Return Value

none

See Also

Hide, Unhide, Enable, ReadOnly, ClearField

DisableUnderneath

DisableUnderneath()

Description

When a drop-list appears it can overlap other fields on the window. These other fields in turn can interact with the list visually, and in responding to mouse-clicks. In order to prevent this fields (wholly or partially) under the list control are disabled while the list is open. This method finds the applicable controls, and disables them.

Parameters

none

Return Value

none

See Also

EnableUnderneath

Drop

Drop (<Long pShow>)

Description

Triggers the same behavior as the user clicking on the drop button.

Parameters

Parameter Description
pShow If true then the Drop list is displayed. If false then the drop list is hidden. If omitted then the state of the drop list is toggled (as if the user pressed on the Drop button.)

Return Value

none

See Also

ShowSuggestions, HideSuggestions

Enable

Enable()

Description

Enable the field (and related fields) on the window.

Parameters

none

Return Value

none

See Also

Hide, Unhide, Disable, ReadOnly

EnableUnderneath

EnableUnderneath()

Description

Enable the fields disabled with a previous call to DisableUnderneath.

Parameters

none

Return Value

none

See Also

DisableUnderneath

GetEntryDescription

GetEntryDescription()

Description

Returns a description for the selected row. By default this is a space separated concatenation of the .RemoteDesc properties. You can override this method to alter the description in some way.

Parameters

none

Return Value

String. The description for the row.

See Also

Controlling the description in the lookup field

Hide

Hide()

Description

Hide the field (and related fields) on the window.

Parameters

none

Return Value

none

See Also

Unhide, Enable, Disable,, ReadOnly, ClearField

HideSuggestions

HideSuggestions()

Description

Hide the drop-list if it is open.

Parameters

none

Return Value

none

See Also

Drop, ShowSuggestions

Init

Init (String pProc, File pTable, Key pIdKey, <Key pDescKey>, Long pEntryControl=0, Long pLookup, Long pAutoComplete, Long pAutoCompleteChars=3, Long pHotKey=0, Long pAutoLookup=0, Long pAllowInvalid=0, Long pAllowBlank=0)

Description

Initializes the object and sets various properties to match desired behaviours.

Parameters

Parameter Description
pProc Sets the .proc property. This is used by the TRACE method for debugging purposes.
pTable The name of the foreign table which this field is looking up on.
pIdKey The Key in the foreign table to use as the ID Key. The ID Key field will usually be the value stored by the calling form.
pDescKey The Key (if it exists) containing the description field. If this is set then the user will see, and can enter, the description field instead of the code field.
pEntryControl The Use Equate of the entry field on the window.
pLookup Set to true if the lookup button should be visible to the user.
pAutoComplete Set to true if the auto-complete functionality (via the drop list) should be visible to the user.
pAutoCompleteChars The minimum number of characters the user needs to type before the auto-complete begins.
pHotKey A hotkey to use to trigger the lookup automatically. Defaults to F2.
pAutoLookup If true, and the user types an invalid entry, then the Lookup window (if it exists) is automatically called.
pAllowInvalid If true the user is allowed to type entries that are not in the foreign table.
pAllowBlank If true then this field is allowed to be blank. If false then this is effectively a REQUIRED field.

Return Value

none

LocalChanged

LocalChanged (Long pDisplay=true)

Description

If the local ID field has changed (in embed code) then this method can be called to load the matching foreign-table record.

Parameters

Parameter Description
pDisplay If true, updates the entry field with the updated description value.

Return Value

none

See Also

Updating the contents of the lookup control when the ID Field changes

LoadSuggestions

LoadSuggestions()

Description

A method that loads suggestions into the drop-list, as the user types.
The suggestions list is a queue (self.Suggestions property) of type SuggestionsQueueType.

Typically the template generates a VIEW in order to populate the suggestions, but you could override this with alternate code if you wanted to.

Parameters

none

Return Value

none

See Also

MakeFilter

MakeFilter

MakeFilter (<string pField1>,....,<string pField10>)

Description

Makes the filter for the VIEW as the user types.

Parameters

Parameter Description
pField1 ... pField10 One or more (up to 10 fields) to do the search on.

Return Value

A filter which can be applied to the VIEW to return a list of suggestions into the drop listbox.

Notes

In builds prior to 1.30 this method had an optional first parameter containing an additional filter to apply. This parameter was removed in build 1.30 and the SetFilter method called instead.

See Also

LoadSuggestions, SetFilter

ReadOnly

ReadOnly (Long pReadOnly=true)

Description

Sets the entry field as read-only.

Parameters

Parameter Description
pReadOnly If true, or omitted, then the entry field is displayed as Readonly. If the field is Readonly then the Drop, Lookup and Clear buttons are hidden. Set this parameter to false to make the field not read-only.

Return Value

none

See Also

Hide, Unhide, Enable, Disable, ClearField

Refresh

Refresh()

Description

Refreshes the state, and position of the various controls, with respect to the entry control. For example if the entry control itself is moved, or hidden, then this method should be called.

Parameters

none

Return Value

none

See Also

Hide, Unhide, Enable, Disable, ReadOnly

SetFilter

SetFilter (String pFilter)

Description

Sets the filter that should be applied to the child table when the user opens the Droplist or types a code or description directly. The filter is not applied at the time this call is made, it just sets the filter for when it is needed. the filter is checked later on by the Checkfilter method.

The filter parameter is tested to make sure it can be evaluated by the VIEW engine later on. If the filter is not correct then the filter is set to false (meaning that no records are available to the user), an error is written to Debugview, and a non-zero value is returned.

Parameters
Parameter Description
pFilter A filter which limits the options available for the user to select, either via the Droplist, or by typing a code, or description directly into the entry field.

Return Value

0 if the filter is syntactically correct, an errorcode() if it is not correct.

See Also

CheckFilter, MakeFilter

SetListPosition

SetListPosition (Long px, Long py, Long pw, Long ph)

Description

Sets the position of the DropList control. Called automatically when the list control is unhidden.

Parameters

Parameter Description
px X Position of the List control
py Y Position of the List control
pw Width of the list control. If the MinDropWidth property is set, and this is less than that, then the MinDropWidth property is used instead.
ph The height of the List control

Return Value

none

See Also



ShowSuggestions

ShowSuggestions (Long pSelect=0)

Description

Shows suggestions to the user (as a drop-down list) as they are typing. If the list is not already visible it will be displayed.

Parameters

Parameter Description
pSelect The row in the list to pre-select.

Return Value

none

See Also

Drop, HideSuggestions

Unhide

Unhide()

Description

Unhide the field (and related fields) on the window.

Parameters

none

Return Value

none

See Also

Hide, Enable, Disable, ReadOnly

SelectRecentManager

The SelectRecentManager is derived from the RecentBase class, so all those methods and properties apply here as well.

Properties

Property Type Description
AllText STRING The text to display at the top of the ALL section in the lookup.
Control LONG The List control into which the recent values will be injected.
CurrentPrimaryKey &KEY A pointer to the primary key of the lookup table.
CurrentRecord &GROUP A pointer to the record structure of the lookup table.
FieldsKey &KEY A pointer to the Fields Key in the RecentLookups table structure.
File &FILE A pointer to the RecentLookups table structure.
IncHeaders LONG If set to true then the ALL and RECENT headers are added into the Queue for the list control.
Initialized LONG An internal property, set when the class has been correctly initialized.
MaxRemember LONG The number of items to store, and display for each lookup. the default value is 5.
PopulateDone LONG Set once the lsit has been populated with the recent values.
Q &QUEUE A pointer to the Queue, which is the source data for the list control.
qName ANY A pointer to the "Header column" field.
qNameStyleFieldNumber LONG The field number, for the Style field, of the Header column.
RecentText STRING The text to display at the top of the RECENT section in the lookup.
tDate &LONG A pointer to a field in the RecentLookups table containing the Date Stamp when the record was last written to.
tFavorite &LONG Reserved for future use.
tID &STRING A pointer to a field in the RecentLookups table containing the ID field (the Primary Key field) for the table itself.
TimeKey &KEY A pointer to the Time Key in the RecentLookups table structure.
tKF &STRING,DIM(MaxKeyFields) An array of pointers to the Key Fields in the RecentLookups Table structure.
tTable &STRING A pointer to the field in the RecentLookups table which contains the Table name.
tTime &LONG A pointer to a field in the RecentLookups table containing the Time Stamp when the record was last written to.
tUser &STRING A pointer to a field in the RecentLookups table containing the User login.
View &VIEW A Pointer to a VIEW structure, used for populating the queue.

Methods

CloseFile

CloseFile()

Description

Closes the RecentLookups table.

Parameters

None

Return Value

None

See Also

OpenFile

GetFieldLabel

GetFieldLabel (*File pFile, Long pX)

Description

Returns the label of a field (not the external name) given a file structure and a field number.

Parameters

Parameter Description
pFile  FILE The name of the File structure.
pFieldNumber Long The Field Number in the structure.

Return Value

A string containing the label of the field.

Init

Init (String pProc, Long pControl, Long pHeaders, String pAllText, String pRecentText)

Description

Initializes the object with some basic behaviours.

Parameters

Parameter Description
pProc  String The name of the procedure which owns the object.
pControl Long The Field Equate (FEQ) of the List Control
pHeaders Long Set to True to include the ALL and RECENT headers in the list.
pAllText String The text to include at the top of the ALL section.
pRecentText String The text to include at the top of the RECENT section.

Return Value

none

IsHeaderSelected

IsHeaderSelected()

Description

Determines if the user just selected a "Header" record. Called from the TakeEvent method. If the user did select a header row then the selection moves down another row.

Parameters

None

Return Value

Returns True if the user just selected the ALL or RECENT header record.

See Also

TakeEvent

OpenFile

OpenFile()

Description

Opens the RecentLookups table.

Parameters

None

Return Value

none

See Also

CloseFile

PopulateFromFile

PopulateFromFile(File pFile, <View pBrowseView>, <String pUser>, String pTable, Long pForce=0)

Description

Adds the headers, and recent selections, to the List control. If the PopulateDone property is already set (and the Force parameter is not set) then

Parameters

Parameter Description
pFile FILE A handle to the table being looked up on.
pBrowseView VIEW (optional) An optional link to the Browse View so that secondary records can be loaded into the "recent" lines.
pUser String (optional) A string identifying the current user in the program. This allows each user to have a different recent selections list.
pTable String (optional) The name of the table being looked up on.
pForce Long (optional) If true then the recent entries are added to the list control, regardless of whether the PopulateDone property is set or not.

Return Value

none

See Also



PopulateFromView

PopulateFromView(<String pUser>, String pTable, Long pForce=0)

Description

Reserved for future use.



PopulateName

PopulateName(String pName)

Description

Adds a header line to the Queue under the List control

Parameters

Parameter Description
pName String The text of the header to add. (This is usually one of self.AllText or self.RecentText

Return Value

None

PrimeRecord

PrimeRecord()

Description

Sets the Date, Time and Key fields in the RecentLookups table. The date and time are primes to now, the Key fields are primed to the key values in the Lookup table.

Parameters

None

Return Value

None

RecordSelected

RecordSelected(File pFile, Long pFavorite=0, <String pUser>, String pTable)

Description

Called when a record in the lookup table has been selected. the selection is stored in the RecentLookups table.

Parameters

Parameter Description
pFile FILE The table which was just used for the Lookup.
pFavorite Long (optional) Set to recent:LookupSelection (the default) or recent:Favorite
pUser String A string containing an identifier for the currently logged in user.
pTable String The name of the table on which the Lookup just occured.

Return Value

None

SetFile

SetFile(File pFile, Key pFieldsKey, Key pTimeKey, *String pId, *Long pFavorite, *String pUser, *String pTable, *Long pDate, *Long pTime, *string pkf1, <*string pkf2>,<*string pkf3>, <*string pkf4>,<*string pkf5>, <*string pkf6>,<*string pkf7>, <*string pkf8>,<*string pkf9>, <*string pkf10>)

Description

Primes all the internal properties with the various keys, and fields, in the RecentLookup table. Usually called as part of the Object Initialization, after the call to .INIT.

Parameters

Parameter Description
pFile FILE The RecentLookups table.
pFieldsKey KEY The key in the RecentLookups table on the Favorite, User, Table , Keyfield1, ... fields
pTimeKey KEY the key in the RecentLookups table on the Favorite, User, Table, Date, Time fields.
pID String The ID field in the RecentLookups Table.
pFavorite Long The FAVORITE field in the RecentLookups Table.
pUser String The USER field in the RecentLookups Table.
pTable String The TABLE field in the RecentLookups Table.
pDate Long The DATE field in the RecentLookups Table.
pTime Long The TIME field in the RecentLookups Table.
pKF1... pKF10 String The Keyfield1 to Keyfield10 fields in the RecentLookups Table.

Return Value

None

SetQueue

SetQueue(Queue pQueue,*? pName)

Description

Sets the internal Q property, and the variable which will be used for header column. Usually called right after the call to .INIT.

Parameters

Parameter Description
pQueue Queue The Queue used by the List control.
pName ANY (optional) The variable assigned to the column in the list box, that should be used as the Header column. (If not specified this defaults to the first String column in the queue.)

Return Value

None


SetQueueRecord

SetQueueRecord()

Description

Populates the Recent row, when a Recent row is added to the List control. This calls the BrowseClass.SetQueueRecord method (in ABC) or the FillQueue routine (in Legacy).

When this method is called the Table record buffer needs to have been loaded.

Parameters

None
 
Return Value

None

SetStyle

SetStyle(Long pUseFor, Long pFrontColor, Long pBackColor, <string pName>, <String pSize>, Long pStyle=700)

Description

Sets the styles to the list box.

Parameters

Parameter Description
pUseFor  Long One of recent:StyleHeader, recent:StyleHeaderX, recent:StyleRecent.

recent:StyleHeader is used for the ALL and RECENT text. recent:styleHeaderX is used for all the other columns in a header row. Typically it's the same as the recent:StyleHeader, but with the text color set to be the same as the background color.

The recent:StyleRecent style is used for the actual rows of recently selected data.
pFrontColor  Long The foreground (text) color
pBackColor Long The background color
pName String (optional) The Font to use.
pSize String (optional) The size of the font to use. This can be a "relative" value, eg '+1' or '-2' and so on.
pStyle Long (optional) the Style value for the font. Font:Regular or Font:Bold and so on.

Return Value

None

SetStylesItem

SetStylesItem(Long pStyle)

Description

Sets the Style and/or Color fields for all columns in a Quick-Selection row.

Parameters

Parameter Description
pStyle Long The style to apply to all the columns.

Return Value

None

See Also

SetStyle, SetStylesHeader

SetStylesHeader

SetStylesHeader(Long pStyleX,Long pStyle)

Description

Sets the Style and/or Color fields in  a row, based on the styles set with the SetStyle method. This method is called when adding the RECENT and ALL heading rows to the list.

Parameters

Parameter Description
pStyleX Long The style for all the columns except the column with ALL or RECENT in it.
pStyle Long The style for the Header column (ie the column with the word ALL and RECENT.

Return Value

None

See Also

SetStyle, SetStylesItem

SetView

SetView(View pView)

Description

Reserved for future Use.


TakeEvent

TakeEvent()

Description

Gets called for every event on the window. Any Event-dependent code is added here.

Parameters

None
 
Return Value

None

SyncBrowseView

SyncBrowseView(View pBrowseView, String pFilter)

Description

Calls either SyncBrowseViewTPS or SyncBrowseSQL depending on the driver used by the primary table in the View.

Parameters
Parameter Description
pBrowseView VIEW The view being used to populate the browse.
pFilter String A filter, constructed in PopulateFromFile, so that the correct record in the view is located.

Return Value

Returns nothing, however the secondary fields are loaded into their respective file records.

See Also

SyncBrowseViewISAM, SyncBrowseViewSQL

SyncBrowseViewISAM

SyncBrowseViewISAM(View pBrowseView, String pFilter)

Description

Loads a record using the Browse View structure, which ensures that all secondary fields joined in the view are loaded.

Parameters
Parameter Description
pBrowseView VIEW The view being used to populate the browse.
pFilter String A filter, constructed in PopulateFromFile, so that the correct record in the view is located.

Return Value

Returns nothing, however the secondary fields are loaded into their respective file records.

See Also

SyncBrowseViewSQL, SyncBrowseView

SyncBrowseViewSQL

SyncBrowseViewSQL(View pBrowseView, String pFilter)

Description

Loads a record using the Browse View structure, which ensures that all secondary fields joined in the view are loaded.

Parameters
Parameter Description
pBrowseView VIEW The view being used to populate the browse.
pFilter String A filter, constructed in PopulateFromFile, so that the correct record in the view is located.

Return Value

Returns nothing, however the secondary fields are loaded into their respective file records.

See Also

SyncBrowseViewISAM, SyncBrowseView

ValidateRecord

ValidateRecord()

Description

Checks to make sure that a recently selected row in the browse, is still valid for the filter being applied to the current lookup browse.

Parameters

None

Return Value

None

See Also



Frequently Asked Questions

  1. Hiding / Unhiding an entry control
  2. Auto-adding a new record that does not exist in the lookup table

1. Hiding / Unhiding an entry control

See the Hide and Unhide methods

2. Auto-adding a new record that does not exist in the lookup table

You can use the AskAllowInvalid method to insert the record (or conditionally accept the record). If the record is successfully added, then return true, otherwise return false and the entry will be handled as an invalid entry.

Support

Your questions, comments and suggestions are welcome. See our web page (www.capesoft.com) for new versions. You can also contact us in one of the following ways:
CapeSoft Support
Email
Telephone +27 87 828 0123 or
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.

Version History

Version 1.41 - 8 January 2024 Version 1.40 - 28 December 2023 Version 1.39 - 13 August 2021 Version 1.38 - 24 May 2021 Version 1.37 (22 March 2021) Version 1.36 (29 December 2020) Version 1.35 (7 September 2020) Version 1.34 (20 May 2020) Version 1.33 (2 August 2019) Version 1.32 (13 Sept 2018) Version 1.31 (16 Aug 2018) Version 1.30 (2 May 2017) Version 1.29 (20 March 2017) Version 1.28 (13 March 2017) Version 1.27 (31 October 2016) Version 1.26 (26 September 2016) Version 1.25 (20 September 2016) Version 1.24 (12 September 2016) Version 1.23 (24 June 2016) Version 1.22 (12 January 2016) Version 1.21 (30 October 2015) Version 1.20 (7 October 2015) Version 1.19 (26 August 2015) Version 1.18 (23 July 2015) Version 1.17 (22 July 2015) Version 1.16 (20 July 2015) Version 1.15 (10 April 2015) Version 1.14 (25 February 2015) Version 1.13 (4 January 2015) Version 1.12 (5 December 2014) Version 1.11 (24 November 2014) Version 1.10 (10 November 2014) Version 1.09 (20 October 2014) Version 1.08 (9 October 2014) Version 1.07 (3 Sept 2014) Version 1.06 (18 July 2014) Version 1.05 (27 January 2014) Version 1.04 (17 December 2013) Version 1.03 (4 December 2013) Version 1.02 (3 December 2013) Version 1.01 (3 December 2013) Version 1.00 (29 November 2013)