The Session Object
| Purpose: | The Session object ⎕SE is a special system object that represents the session window and acts as a parent for the session menus, tool bar(s) and status bar. |
| Children | Form, MenuBar, Menu, MsgBox, Font, FileBox, Printer, Bitmap, Icon, Cursor, Clipboard, Locator, Timer, Metafile, ToolBar, StatusBar, TipField, TabBar, ImageList, PropertySheet, OLEClient, TCPSocket, CoolBar, ToolControl, BrowseBox |
| Properties | Type, Caption, Posn, Size, File, Coord, State, Event, FontObj, YRange, XRange, Data, TextSize, Handle, HintObj, TipObj, CurObj, CurPos, CurSpace, Log, Input, Popup, RadiusMode, LogFile, MethodList, ChildList, EventList, PropList |
| Methods | ChooseFont, FileRead, FileWrite |
| Events | Close, Create, FontOK, FontCancel, WorkspaceLoaded, SessionPrint, SessionTrace |
Description
There is one (and only one) object of type Session and it is called ⎕SE. You may use ⎕WG, ⎕WS and ⎕WN to perform operations on ⎕SE, but you cannot expunge it with ⎕EX nor can you recreate it using ⎕WC. You may however expunge all its children. This will result in a bare session with no menu bar, tool bar or status bar.
⎕SE is loaded from a session file when APL starts. The name of the session file is specified by the session_file parameter. If no session file is defined, ⎕SE will have no children and the session will be devoid of menu bar, tool bar and status bar components.
An additional feature is provided to establish code in the Session. See .
You may use all of the standard GUI system functions to build or configure the components of the Session to your own requirements. You may also control the Session by changing certain of its properties.
Note that the Session reports a Create event when APL is first started, and a WorkspaceLoaded event when a workspace is loaded or on a clear ws.
The Session reports a SessionPrint event when certain types of output are about to be displayed. This may be used to alter the normal default display. The Session also reports a SessionTrace event when executing when an expression is execute with trace control. This may be used to alter the normal default trace.
Read-Only Properties
The following properties of ⎕SE are read-only and may not be set using ⎕WS:
| Property | Description |
|---|---|
| Type | A character vector containing 'Session' |
| Caption | A character vector containing the current caption in the title bar of the Session window. |
| TextSize | Reports the bounding rectangle for a text string. For a full description, see TextSize in Object Reference. |
| CurObj | A character vector containing the name of the current object. This is the name under or immediately to the left of the input cursor. |
| CurPos | A 2-element integer vector containing the position of the input cursor (row and column number) in the session log. This is ⎕IO dependent. If ⎕IO is 1, and the cursor is positioned on the character at the beginning of the first (top) line in the log, CurPos is (1 1). If ⎕IO is 0, its value would be (0 0). |
| CurSpace | A character vector which identifies the namespace from which the current expression was executed. If the system is not executing code, CurSpace is the current space and is equivalent to the result of ⊃''⎕NS'' . |
| Handle | The window handle of the Session window. |
| Log | A vector of character vectors containing the most recent set of lines (input statements and results) that are recorded in the session log. The first element contains the top line in the log. |
| Input | A vector of character vectors containing the most recent set of input statements (lines that you have executed) contained in the input history buffer. |
| LogFile | The name of the session log file in use. |
| ChildList | A vector of character vectors containing the types of object that can be created as a child of ⎕SE . |
| MethodList | A vector of character vectors containing the names of the methods associated with ⎕SE . |
| EventList | A vector of character vectors containing the names of the events generated by ⎕SE |
| PropList | A vector of character vectors containing the names of the properties associated with ⎕SE . |
Read/Write Properties
The following properties of ⎕SE may be changed using ⎕WS:
| Property | Description |
|---|---|
| Caption | A character vector containing the current caption in the title bar of the Session window. See Session Caption . |
| Coord | Specifies the co-ordinate system for the session window. |
| Data | May be used to associate arbitrary data with the session object ⎕SE . |
| Event | You may use this property to attach an expression or callback function to the Create event or to user-defined events. A callback attached to the Create event can be used to initialise the Session when APL starts. |
| File | The full pathname of the session file that is associated with the current session. This is the file name used when you save or load the session by invoking the FileRead or FileWrite method. |
| FontObj | Specifies the APL font. In general, the FontObj property may specify a font in terms of its face name, size, and so forth or it may specify the name of a Font object. For applications, the latter method is recommended as it will result in better management of font resources. However, in the case of the Session object, it is recommended that the former method be used. |
| HintObj | Specifies the name of the object in which hints are displayed. Unless you specify HintObj individually for session components, this object will be used to display the hints associated with all of the menu items, buttons, and so forth in the session. The object named by this property is also used to display the message "Ready..." when APL is waiting for input. |
| Popup | A character vector that specifies the name of a popup menu to be displayed when you click the right mouse button in a Session window. |
| Posn | A 2-element numeric vector containing the position of the top-left corner of the session window relative to the top-left corner of the screen. This is reported and set in units specified by the Coord property. |
| Size | A 2-element numeric vector containing the height and width of the session window expressed in units specified by the Coord property. |
| State | An integer that specifies the window state (0=normal, 1=minimised, 2=maximised). You may wish to use this property to minimise and later restore the session under program control. If you save your session with State set to 2, your APL session will start off maximised. |
| TipObj | Specifies the name of the object in which tips are displayed. Unless you specify TipObj individually for session components, this object will be used to display the tips associated with all of the menu items, buttons, and so forth in the session. |
| XRange | See Object Reference |
| YRange | See Object Reference |
Special Properties
The following properties of ⎕SE are used internally by Dyalog tools such as SALT. They are not intended nor supported for general use and are not reported by PropList.
| StatusWindow | This read-only property returns a reference to the Status Window. The expression: (⎕SE.⎕WG'StatusWindow')⎕WG'Text' returns the (read-only) contents of the status window. |
| Editor | This read-only property returns a reference to the Editor Window. The Editor generates the special events Fix , AfterFix and Format . |
Special Events
The following special events are generated by ⎕SE or its child objects. They are used internally by Dyalog tools such as SALT. They are not intended nor supported for general use.
| AfterFix | This event is reported by the Editor after it has successfully fixed a new object, or a new version of an object, in the workspace. |
| Fix | This event is reported by the Editor when the user attempts to fix an object. |
| Format | This event is reported by the Editor when the user attempts to format an object. |
| SessionPrint | This event is reported when a value is about to be displayed in the Session window. The default display of the value may be intercepted by a callback function and displayed differently. This event is used by the ]box and ]rows user commands. |
| SessionTrace | This event is reported when an expression is executed with trace control. The trace behaviour may be intercepted by a callback function and altered. This event is used by the ]box and ]rows user commands. |
| WorkspaceLoaded | This event is generated when a workspace is loaded or upon )CLEAR . |
Session Caption
The Caption property of the Session may be set dynamically to a character vector comprising free text and field names. Field names must be enclosed in braces and are replaced in-situ by corresponding values.
| Field Name | Description |
|---|---|
| {TITLE} | the window specific text |
| {WSID} | ⎕WSID |
| {NSID} | current namespace |
| {SNSID} | short version of namespace (no # .) |
| {PRODUCT} | for example, Dyalog APL/W |
| {VER_A} | for example, 19 |
| {VER_B} | for example, 0 |
| {VER_C} | for example, 47586 (SVN revision) |
| {PID} | process ID (decimal) |
| {CHARS} | "Classic" or "Unicode" |
| {BITS} | "32" or "64" |
Example
⎕SE.Caption←'Pete: {WSID} {Product} {VER_A}.{VER_B}'
The Session caption in a CLEAR WS will change to:
Pete: CLEAR WS Dyalog APL/W-64 19.0
Note that Caption returns the codified string used to set it.
⎕SE.Caption
Pete: {WSID} {Product} {VER_A}.{VER_B}