REF OPENLOOK Jonathan Meyer, Andreas Schoter Sep 1991 Revised, John Gibson Apr 1993 COPYRIGHT University of Sussex 1993. All Rights Reserved. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< THE POPLOG OPENLOOK >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< INTERFACE >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< This file provides some programming details of the Poplog interface to the Open Look Intrinsics Toolkit Widget Set (sometimes referred to as OLIT or Xol, this widget set is referred to as OpenLook in this document). See HELP * OPENLOOK for an overview of the Poplog OpenLook interface. CONTENTS - (Use g to access required sections) 1 Loading OpenLook Widgets 2 Different Versions Of OpenLook 3 OpenLook Startup 4 OpenLook Procedures 5 OpenLook Widget Classes 5.1 Widgets 5.2 Gadgets 5.3 Objects 6 Include Files: Constants and Typespecs 7 Additional Data Structures 8 Function And Procedure Resources 9 ScrollingList Widget Support 9.1 Example 10 Unsupported Features 10.1 Pop-11 Procedure Registration 10.2 Pixel Conversion Routines 11 Associated Documentation --------------------------- 1 Loading OpenLook Widgets --------------------------- To use OpenLook library files, it is first necessary to extend popuseslist to include the Xol sub-directory of the main Poplog X library. This is done with uses Xol; For each OpenLook widgetclass, the Xol directory defines a constant identifier xolFooBazWidget (in a file of that name) which you must 'use' in order to use the widgetclass, i.e. uses xolFooBazWidget; Thus for example, the OpenLook C widget class name rectButtonWidgetClass is mapped onto the Poplog name xolRectButtonWidget: uses xolRectButtonWidget; xolRectButtonWidget => Alternatively, you can use LIB * XolAllWidgets: uses XolAllWidgets; This is an Xol library file containing a uses for every widget, and so loads them all once. --------------------------------- 2 Different Versions Of OpenLook --------------------------------- There are several differences between different releases of the OpenLook Toolkit Intrinsics. To enable Poplog to work correctly with the different versions the constant XOL_VERSION is provided. For this to be set, the Poplog image must either have be linked with OLIT with a value for XLINK_VERSION defined, or the environment variable POP_XOL_EXLIBS must supply a value. See Poplog Image X Link Specification in REF * X. The value will be an integer of the form (MAJOR-RELEASE-NUMBER * 1000) + MINOR-RELEASE-NUMBER For example, when using version 3.0 of OLIT, XOL_VERSION should contain the integer 3000. XOL_VERSION -> int [constant] This is an autoloadable constant. If * popxlink_openlook is defined (i.e. Poplog was linked with OLIT), and the link defined XLINK_VERSION, then its value is XLINK_VERSION. Otherwise, when XOL_VERSION is loaded, it tries to get a value from the environment variable POP_XOL_EXLIBS using * sys_translate_exlibs. If this fails, the mishap 'NO OPENLOOK VERSION (XOL_VERSION) AVAILABLE' occurs. ------------------- 3 OpenLook Startup ------------------- When you load an OpenLook widgetclass, the OpenLook procedure OlToolkitInitialize is either automatically called (if sysxsetup has already been called), or added to the Poplog toolkit initialisation procedure XptToolkitInitialize to be called when sysxsetup is run. Thus you need take no further action in this respect. ---------------------- 4 OpenLook Procedures ---------------------- When any of the OpenLook widgetclasses are loaded, they load a number of OpenLook convenience functions (starting with Ol-), and also define several additional procedures needed to use OpenLook in Poplog (starting with Xpol-). Additional functions may also be defined when you request specific widgets from the OpenLook widget set. Procedures starting with Ol- follow the same calling semantics as their C equivalents, and do NOT perform any type checking on their arguments. Xpol- procedures on the other hand do perform any necessary type checking. (The files defining the Xol- procedures employ XptPopLoadProcedures to load them.) OlCanAcceptFocus(arg1, arg2) -> bool [procedure] OlConvertVirtualTranslation(string1) -> string2 [procedure] OlCreatePackedWidget(arg1) -> widget [procedure] OlCreatePackedWidgetList(arg1, arg2) -> widget [procedure] OlError(arg1) [procedure] OlFlatGetValues(arg1, ... arg4) [procedure] OlFlatSetValues(arg1, ... arg4) [procedure] OlGetResolution(arg1) -> byte [procedure] OlHasFocus(arg1) -> bool [procedure] OlPostInitialize(arg1, ... arg5) [procedure] OlPreInitialize(arg1, ... arg5) [procedure] OlRegisterHelp(arg1, ... arg5) [procedure] OlSetVaDisplayErrorMsgHandler(arg1, arg2) [procedure] OlSetVaDisplayWarningMsgHandler(arg1, arg2) [procedure] OlSetErrorHandler(arg1) [procedure] OlSetWarningHandler(arg1) [procedure] OlVaDisplayErrorMsg(argvarargs) [procedure] OlVaDisplayWarningMsg(argvarargs) [procedure] OlWarning(arg1) [procedure] These procedures are in LIB * Xolgeneral, which is loaded automatically by every widget class. BufferFilled(buffptr) -> bool [procedure] BufferLeft(buffptr) -> bool [procedure] BufferEmpty(buffptr) -> bool [procedure] These procedures are provided as buffer interface utilities by LIB * Xolbuffer, loaded automatically by xolTextEditWidget. LookupOlInputEvent(widget, xeventptr, ulong, charptrptr, [procedure] intvec) -> olinputcalldataptr OlReplayBtnEvent(widget, uint, xeventptr) [procedure] OlDetermineMouseAction(widget, xeventptr) -> exptr [procedure] OlGrabDragPointer(widget, XID1, XID2) [procedure] OlUngrabDragPointer(widget) [procedure] OlDragAndDrop(widget, ulongptr, intvec1, intvec2) [procedure] OlRegisterDynamicCallback(p, uint) [procedure] OlUnregisterDynamicCallback(p, uint) -> int [procedure] OlCallDynamicCallbacks() [procedure] These procedures are in LIB * XolDynamic, which is loaded automatically by xolTextEditWidget. For more details on the individual functions please see the man page entries in /usr/openwin. GetOlMoveCursor(screenptr) -> XID [procedure] GetOlDuplicateCursor(screenptr) -> XID [procedure] GetOlBusyCursor(screenptr) -> XID [procedure] GetOlPanCursor(screenptr) -> XID [procedure] GetOlQuestionCursor(screenptr) -> XID [procedure] GetOlTargetCursor(screenptr) -> XID [procedure] GetOlStandardCursor(screenptr) -> XID [procedure] OlGet50PercentGrey(screenptr) -> XID [procedure] OlGet75PercentGrey(screenptr) -> XID [procedure] These procedures are loaded by LIB * XolOlCursor. For more details on the individual procedures please refer to the man page entries in /usr/openwin/share/man. AllocateBuffer(int1, int2) -> buffptr [procedure] GrowBuffer(buffptr, int) [procedure] CopyBuffer(buffptr1) -> buffptr2 [procedure] FreeBuffer(buffptr) [procedure] InsertIntoBuffer(buffptr1, buffptr2, int1) -> int2 [procedure] ReadFileIntoBuffer(FP, buffptr) -> int [procedure] ReadStringIntoBuffer(buffptr1, buffptr2) -> int [procedure] Ol_stropen(string) -> buffptr [procedure] Ol_strgetc(buffptr) -> int [procedure] Ol_strclose(buffptr) [procedure] Ol_streexp() -> string [procedure] Ol_strexp(string1, string2, string3) -> string4 [procedure] Ol_strrexp(string1, string2, string3) -> string4 [procedure] AllocateTextBuffer(string, p, uint) -> textbuffptr [procedure] FreeTextBuffer(textbuffptr, p, uint) [procedure] ReadFileIntoTextBuffer(string, p, uint) -> textbuffptr [procedure] ReadStringIntoTextBuffer(string, p, uint) -> textbuffptr [procedure] GetTextBufferLocation(textbuffptr, int, textlocptr) [procedure] -> string ForwardScanTextBuffer(textbuffptr, textlocptr, string) [procedure] -> int BackwardScanTextBuffer(textbuffptr, string, textlocptr) [procedure] -> int ReplaceBlockInTextBuffer(textbuffptr1, textlocptr1, [procedure] textlocptr2, string, p, uint) -> int ReplaceCharInTextBuffer(textbuffptr, textlocptr, int, P, [procedure] uint) -> int IncrementTextBufferLocation(textbuffptr, textlocptr1, [procedure] int1, int2) -> textlocptr2 LocationOfPosition(textbuffptr, int) -> textlocptr [procedure] LineOfPosition(textbuffptr, int1) -> int2 [procedure] PositionOfLocation(textbuffptr, textlocptr) -> int [procedure] PositionOfLine(textbuffptr, int1) -> int2 [procedure] LastTextBufferPosition(textbuffptr) -> int [procedure] LastTextBufferLocation(textbuffptr) -> textlocptr [procedure] StartCurrentTextBufferWord(textbuffptr, textlocptr1) [procedure] -> textlocptr2 EndCurrentTextBufferWord(textbuffptr, textlocptr1) [procedure] -> textlocptr2 PreviousTextBufferWord(textbuffptr, textlocptr1) [procedure] -> textlocptr2 NextTextBufferWord(textbuffptr, textlocptr1) -> textlocptr2 [procedure] NextLocation(textbuffptr, textlocptr1) -> textlocptr2 [procedure] PreviousLocation(textbuffptr, textlocptr1) -> textlocptr2 [procedure] GetTextBufferLine(textbuffptr, int) -> string [procedure] GetTextBufferChar(textbuffptr, textlocptr) -> int [procedure] CopyTextBufferBlock(textbuffptr, charptr, int1, int2) [procedure] -> int3 GetTextBufferBlock(textbuffptr, textlocptr1, textlocptr2) [procedure] -> string GetTextBufferBuffer(textbuffptr, int) -> exptr [procedure] SaveTextBuffer(textbuffptr, string) -> int [procedure] RegisterTextBufferUpdate(textbuffptr, p, uint) [procedure] UnregisterTextBufferUpdate(textbuffptr, p, uint) -> int [procedure] RegisterTextBufferScanFunctions(p1, p2) [procedure] RegisterTextBufferWordDefinition(p) [procedure] These procedures are in LIB * Xolbuffer, which is loaded automatically by xolTextEditWidget. For details of the individual procedures please refer to the relevant man pages in /usr/openwin/share/man. OlCallAcceptFocus(arg1, arg2) -> bool [procedure] OlMoveFocus(arg1, arg2, arg3) -> widget [procedure] These procedures are in LIB * XolManager, which is loaded automatically by # xolBulletinBoardWidget # xolCaptionWidget # xolCheckBoxWidget # xolControlAreaWidget # xolExclusivesWidget # xolHelpWidget # xolManagerWidget # xolNonexclusivesWidget # xolTextFieldWidget # xolTextWidget OlMenuPost(widget) [procedure] OlMenuUnpost(widget) [procedure] These procedures are in LIB * XolMenu, which is loaded automatically by # xolAbbrevMenuButtonWidget # xolMenuButtonGadget # xolMenuButtonWidget # xolMenuShellWidget Note that widget must be of class MenuShell. OlTextEditClearBuffer(widget) -> bool [procedure] OlTextEditCopyBuffer(arg1, arg2) -> bool [procedure] OlTextEditCopySelection(widget, int) -> bool [procedure] OlTextEditReadSubString(widget, charptrptr, int1, int2) [procedure] -> bool OlTextEditGetLastPosition(widget, intvec) -> bool [procedure] OlTextEditGetCursorPosition(widget, intvec1, intvec2, [procedure] intvec3) -> bool OlTextEditInsert(widget, string, int) -> bool [procedure] OlTextEditPaste(widget) -> bool [procedure] OlTextEditSetCursorPosition(widget, int1, int2, int3) [procedure] -> bool OlTextEditRedraw(widget) -> bool [procedure] OlTextEditUpdate(widget, bool1) -> bool2 [procedure] OlTextEditTextBuffer(widget) -> textbuffptr [procedure] These procedures are loaded by xolTextEditWidget. For more details on the individual procedures please refer to the man pages in /usr/openwin/share/man. OlTextFieldCopyString(widget, charptr) -> int [procedure] OlTextFieldGetString(widget, intvec) -> string [procedure] These procedures are loaded by xolTextFieldWidget. For more details on the individual procedures please refer to the relevant man pages in /usr/openwin/share/man. OlListItemPointer(token) -> listitem [procedure] This procedure is loaded by xolScrollingListWidget. For more details on the individual procedures please refer to the relevant man pages in /usr/openwin/share/man. InitializeOpenLook( ...) [procedure] SetWMDecorationHints( ...) [procedure] SetWMState( ...) [procedure] SetWMWindowBusy( ...) [procedure] SendProtocolMessage( ...) [procedure] SetWMPushpinState( ...) [procedure] GetOLWinAttr( ...) [procedure] GetOLWinColors( ...) [procedure] EnqueueCharProperty( ...) [procedure] GetHelpKeyMessage( ...) -> int [procedure] GetCharProperty( ...) -> string [procedure] GetAtomList( ...) -> exptr [procedure] These procedures are imported by LIB * XolClients. They are not documented and are of unknown arity, but are included for completeness. -------------------------- 5 OpenLook Widget Classes -------------------------- Each of the widgetclasses below is loaded by a file of the same name in the Xol directory (the files use * XptLoadWidgetClass to load each class). XolAllWidgets [library] This library loads all the widgetclasses below in one go. 5.1 Widgets ------------ xolAbbrevMenuButtonWidget -> widgetclass [constant] Label-less MenuButtonWidget. xolBulletinBoardWidget -> widgetclass [constant] A 'Container Widget': basic non-constraint layout widget. xolCaptionWidget -> widgetclass [constant] A 'Container Widget': wraps a label around a single child. xolCheckBoxWidget -> widgetclass [constant] An 'Action Widget': boolean on-off "tick" button. xolControlAreaWidget -> widgetclass [constant] A 'Container Widget': layout widget for row/column panels. xolExclusivesWidget -> widgetclass [constant] A 'Container Widget': a single choice RectButton/CheckBox manager. xolFlatCheckBoxWidget -> widgetclass [constant] A 'Container Widget': an efficient CheckBox manager. xolFooterPanelWidget -> widgetclass [constant] A 'Container Widget': a simple main window/footer window manager. xolFormWidget -> widgetclass [constant] A 'Container Widget': constraint layout widget. xolMenuShellWidget -> widgetclass [constant] A 'Pop Up Widget': a pop up menu shell. xolMenuButtonWidget -> widgetclass [constant] An 'Action Widget': button with pop up menu associated with it. xolNonexclusivesWidget -> widgetclass [constant] A 'Container Widget': a multi-choice RectButton manager. xolNoticeShellWidget -> widgetclass [constant] A 'Pop Up Widget': a modal pop up for messages and prompts. xolOblongButtonWidget -> widgetclass [constant] An 'Action Widget': button for invoking an action. xolPopupWindowShellWidget -> widgetclass [constant] A 'Pop Up Widget': a modeless pop up for dialog boxes. xolRectButtonWidget -> widgetclass [constant] An 'Action Widget': a toggle button for multi-choice. xolScrollbarWidget -> widgetclass [constant] An 'Action Widget': a scrollbar widget with pop up menu xolScrolledWindowWidget -> widgetclass [constant] A 'Container Widget': a viewport on a child widget. xolScrollingListWidget -> widgetclass [constant] A 'Container Widget': a selection widget with scrolling items list. xolSliderWidget -> widgetclass [constant] An 'Action Widget': thermometer widget. xolStaticTextWidget -> widgetclass [constant] A 'Text Widget': contains non-changeable text. xolStubWidget -> widgetclass [constant] An 'Action Widget': basic widget for graphics output xolTextFieldWidget -> widgetclass [constant] A 'Text Widget': single line (scrolling) text entry field. xolArrowWidget -> widgetclass [constant] xolBaseWindowShellWidget -> widgetclass [constant] xolButtonWidget -> widgetclass [constant] xolDrawAreaWidget -> widgetclass [constant] xolDropTargetWidget -> widgetclass [constant] xolFlatExclusivesWidget -> widgetclass [constant] xolFlatNonexclusivesWidget -> widgetclass [constant] xolFlatWidget -> widgetclass [constant] xolGaugeWidget -> widgetclass [constant] xolHelpWidget -> widgetclass [constant] xolListPaneWidget -> widgetclass [constant] xolMagWidget -> widgetclass [constant] xolManagerWidget -> widgetclass [constant] xolPushpinWidget -> widgetclass [constant] xolRubberTileWidget -> widgetclass [constant] xolTextEditWidget -> widgetclass [constant] These Widget Classes are members of the OpenLook widget set. 5.2 Gadgets ------------ xolButtonGadget -> widgetclass [constant] xolMenuButtonGadget -> widgetclass [constant] xolOblongButtonGadget -> widgetclass [constant] These Gadget Classes are members of the OpenLook widget set. 5.3 Objects ------------ xolEventObj -> widgetclass [constant] This Object Class is a member of the OpenLook widget set. ----------------------------------------- 6 Include Files: Constants and Typespecs ----------------------------------------- The following include files are available for OpenLook; you can include or loadinclude them: # INCLUDE * XolClients # INCLUDE * XolConstants # INCLUDE * XolDynamic # INCLUDE * XolFlat # INCLUDE * XolFont # INCLUDE * XolScroll # INCLUDE * XolTextEdit # INCLUDE * XolTextField # INCLUDE * Xolbuffer (note that these are in the main Poplog X include directory, so don't actually require uses Xol; to make them accessible). Most OpenLook constants are declared as Pop-11 iconstants in these files, the majority of them in INCLUDE * XolConstants. In addition, typespecs for all OpenLook structures are provided, so that it is possible to access data in these structures using exacc. All such typespecs have the same name as their C counterparts. For example, the typespec OlScrollbarVerify can be used to access the call data of a callback attached to a ScrollbarWidget: include XolScroll; define scrollbar_callback(widget, client_data, call_data); lvars widget, client_data, call_data; ;;; accept the new position true -> exacc :OlScrollbarVerify call_data.ok; ;;; print out the location exacc :OlScrollbarVerify call_data.new_location => enddefine; Buffer [typespec] This structure is defined in INCLUDE * Xolbuffer as: i_typespec Buffer { size :int, used :int, esize :int, p :exptr, }; OlDynamicColors [typespec] This structure is defined in INCLUDE * XolDynamic as: i_typespec OlDynamicColors { textForeground :ulong, textBackground :ulong, inputFocus :ulong }; OlInputCallData [typespec] This structure is defined in INCLUDE * XolDynamic as: i_typespec OlInputCallData { consumed :ShortBool, event :exptr, keysym :ulong, buffer :ntstring_ptr, length :exptr.:int, ol_event :uint }; ----------------------------- 7 Additional Data Structures ----------------------------- Additional data structure support is provided by shadowclass definitions. These are used in situations where you need to build data structures in Poplog to pass out to OpenLook, and follow similar naming conventions to the shadowclasses defined by the Poplog X Toolkit. Currently, there is only one shadowclass, for the OlListItem structures used by xolScrollingListWidget: XpolListItemPtr [shadowclass] This is the shadowclass definition for OlListItem structures, as follows: shadowclass XpolListItemPtr [props OlListItemPtr] { XpolLILabelType :short, XpolLILabel :XptString, XpolLIGlyph :exptr, XpolLIAttr :ulong, XpolLIUserData :exptr, XpolLIMnemonic :byte, }; The following code creates a blank OlListItem structure and then sets its label and label_type fields: include XolConstants; uses xolScrollingListWidget; ;;; create a new blank scrolling list item vars list_item = initXpolListItemPtr(); ;;; set label and label_type fields in item 'Hello' -> list_item.XpolLILabel; OL_STRING -> list_item.XpolLILabelType; ----------------------------------- 8 Function And Procedure Resources ----------------------------------- Some OpenLook C procedures are stored as resources in a widget. In order to access and call these procedures, you first need to get the value of the resource as an external procedure type, and then call the procedure using exacc. For example, the scrolling list widget has a procedure stored in the resource called XtN applTouchItem. The following Pop-11 code shows you how to get that procedure and call it: include XolScroll; ;;; get the procedure out of the widget vars applTouchItem = XptVal list_widget(XtN applTouchItem:XptProcedure); ;;; call the procedure exacc applTouchItem(list_widget, list_item); Note that exacc will only check the number of arguments and not their types. Note that the OpenLook ScrollingList procedure in the XtN applAddItem resource expects a C OlListItem structure (not a pointer to a structure, as with most X toolkit procedures) as one of its arguments. Because Poplog does not support the ability to pass structures directly on the call stack, this procedure cannot be made directly available to Poplog users. For this reason, the procedure XpolAddListItem is provided instead by xolScrollingListWidget: XpolAddListItem(widget, parent, reference, item) -> token [procedure] This procedure is identical in calling semantics to the procedure held in the XtN applAddItem resource of ScrollingList widgets, except that item is a pointer to an OlListItem structure (eg. as returned by the initXpolListItemPtr procedure), rather than an OlListItem structure itself. XpolAddListItem calls a C wrapper procedure which then dereferences ITEM into an OlListItem structure, and then calls the XtN applAddItem procedure. widget should be an OpenLook ScrollingListWidget. parent and reference should be OlListToken descriptors, or false to indicate a NULL (0) token. item should be an instance of the XpolListItemPtr shadowkey. XpolAddListItem returns the OlListToken of the new entry to the list. ------------------------------- 9 ScrollingList Widget Support ------------------------------- LIB * XPOL_LISTUTILS provides a simple to use Pop-11 interface to the OpenLook ScrollingListWidget. It provides the programmer with a more friendly interface to the OpenLook ScrollingListWidget. The facilities in LIB * XPOL_LISTUTILS all work together -- if you call the ScrollingListWidget list manipulation routines directly to change the list entries, the procedures provided in LIB * XPOL_LISTUTILS may cease to function correctly. The XpolListItems, XpolSubscrListItems, XpolSelectedListItems and XpolCurrentListItem procedures can all take an optional true as their final argument. Providing this true argument will make the procedures work in "OLLISTTOKEN" mode, where they return the raw list tokens rather than Poplog ITEMS. This may be useful in a few cases where the programmer needs to get at the tokens directly. XpolListItems allows the items of the list to be set using either a Pop-11 list or a repeater. XpolListItems(widget) -> list [procedure] list -> XpolListItems(widget) See below for examples of using XpolListItems. widget should be an instance of an OpenLook ScrollingListWidget. In update mode, this procedure takes a list of Poplog items, (the list can be a dynamic list). It uses the widget's list manipulation procedures to modify the scrolling-list so that it displays the items as they would be printed from Poplog. The procedure attempts to optimise changes to the scrolling-list. So re-assigning an equivalent Pop-11 list to the scrolling-list will not cause the widget to redisplay. In repeated calls to the updater of XpolListItems, the scrolling-list items are only changed when their Poplog counterparts are changed. New items are only added when necessary; rather than recreating the scrolling-list each time, the labels for the current items in the list are updated. In non-update mode, XpolListItems returns a dynamic list, which when flattened will be the full list of items in the scrolling list. It will only work with scrolling-list widgets where the items in the list have been set using the update form of XpolListItems. XpolListTokenToItem(ollisttoken) -> item [procedure] Takes an OlListToken as returned by the XtN applAddItem widget procedure for ScrollingListWidgets. If the token corresponds to a scrolling-list entry that was set by XpolListItems, then the Poplog item associated with that list entry is returned. Otherwise the label for the token (as a string) is returned. XpolItemToToken(widget, item) -> ollisttoken [procedure] Searches down the list of items associated with the ScrollingListWidget widget, and returns the ollisttoken associated with item if item is found in the list, or false otherwise. If the same item appears twice in the list, the token for the first occurrence of item is returned. XpolCurrentListItem(widget) -> item [procedure] item -> XpolCurrentListItem(widget) Sets or retrieves the "current" list entry for ScrollingListWidget widget. The list entry ollisttoken associated with item is found using XpolItemToToken (see above). XpolCurrentListItem ensures that only one entry in the list is the "current" list entry. The current entry is highlighted by drawing a thin rectangle around it. Calling the updater of XpolListItems will clear the "current" item. Note that the ScrollingListWidget also has the notion of "selected" entries, which are highlighted in inverse video, and are used to copy entries of the scrolling list to the X clipboard. To disable this feature, you can set the XtN selectable resource for the list to false. See below for an example of using XpolCurrentListItem. XpolSelectedListItems(widget) -> list [procedure] Returns a (dynamic) list of the items that are "selected" for ScrollingListWidget widget. This is a "read-only" scrolling list attribute, hence there is no updater for XpolSelectedListItems. List selections are used for copying items of the list onto the global X clipboard. More than one list item can be "selected". See XpolCurrentListItem above for information about how to set the single "current" item for a scrolling list. XpolSubscrListItems(N, widget) -> item [procedure] item -> XpolSubscrListItems(N, widget) Accesses or updates the item associated with the N-th list entry of ScrollingListWidget widget. List entries should be specified using XpolListItems (see above). This procedure can be used to change the label of a list entry without having to change the whole list. XpolNumListItems(widget) -> N [procedure] Returns the number of items currently displayed in ScrollingListWidget widget. 9.1 Example ------------ The following is a simple example of the facilities described in the previous section. uses popxlib, Xol; exload_batch; uses xt_widget, xt_callback, xpol_listutils, xolBaseWindowShellWidget, xolScrollingListWidget, ; endexload_batch; XptDefaultSetup(); vars basewin = XtAppCreateShell('panel', 'Demo', xolBaseWindowShellWidget, XptDefaultDisplay, XptArgList([])); /* make the scrolling list -- XtN selectable is false because we are using the XpolCurrentListItem procedure */ vars scroll = XtCreateManagedWidget('myslider', xolScrollingListWidget, basewin, XptArgList([{selectable ^false}])); XtRealizeWidget(basewin); ;;; Set the list to display some items [1 2 3 'hello' world ^true] -> XpolListItems(scroll); ;;; making one of the entries current: 1 -> XpolCurrentListItem(scroll); "world" -> XpolCurrentListItem(scroll); ;;; Setting the list using a repeater procedure: pdtolist(sys_file_match('$HOME/*','',false,false)) -> XpolListItems(scroll); ;;; Clearing the list [] -> XpolListItems(scroll); ;;; Change the list to display the word None and the number 1 [None 1] -> XpolListItems(scroll); ;;; Getting items displayed on the list vars rep = XpolListItems(scroll); rep => ** [...] flatten(rep) => ** [None 1] ;;; Note that Poplog items for each scrolling list item are ;;; returned, so the second item returned will be an integer(1): rep(2) + 1 => ** 2 ;;; Adding a callback to the list: define list_cb(w, client, call); lvars w, client, call; ;;; call is a pointer to an OlListItem. Get the Poplog data ;;; associated with that list entry and print it out with its ;;; key XpolListTokenToItem(call) -> call; ;;; make it current call -> XpolCurrentListItem(w); ;;; print it out {%call, datakey(call)%} => enddefine; XtAddCallback(scroll, XtN userMakeCurrent, list_cb, undef); [1 ^true 3 'hello' goodbye ] -> XpolListItems(scroll); ------------------------ 10 Unsupported Features ------------------------ The following sections detail parts of the OpenLook interface which are, as yet, unsupported. 10.1 Pop-11 Procedure Registration ----------------------------------- Several OpenLook procedures, for example OlSetErrorHandler, take C procedures as arguments. Currently there is no support for supplying Pop-11 procedures instead. Procedures written in C using the Pop-11 callback mechanism can be used in situations where such functionality is essential. See REF * EXTERNAL for details on the external callback mechanism. 10.2 Pixel Conversion Routines ------------------------------- The Poplog OpenLook interface does not define Pop-11 procedures for the C macros in OpenLook to perform pixel conversions. For details of a much more generic facility for performing such conversions, see HELP * XptConvertUnit. ---------------------------- 11 Associated Documentation ---------------------------- HELP * OPENLOOK Overview of Poplog OpenLook Widget Set interface. TEACH * OPENLOOK Tutorial introduction to some OpenLook Widgets. --- C.x/x/pop/ref/openlook --- Copyright University of Sussex 1993. All rights reserved.