PCE version 4C hlp_bufferfirst_fragment last_fragmenteditorsmodifiedundo_buffer_sizesyntaxrequest_renumberfileOIxC hlp_fragment text_buffernextpreviousstylelabelOIxRIC hlp_header text_buffernextpreviousstylelabelOIxRIOIxRIOIxRIOIxRIOIxRIOIxRIOI xRIOI xRIOI xRIOI xRIOI xRIOIxRIOIxRIOIxRIOIxRIOIxRIOIxRIOIxRIOIxRIOIxRIOIxRIOIxRIOIxRIOIxRIOIxRIOIxRIOIxRIOIxRIOIxRIOI xRIOI!xRIOI"xRIOI#xRIOI$xRIOI%xRIOI&xRIOI'xRIOI(xRIOI)xRIOI*xRIOI+xRIOI,xRIOI-xRIOI.xRIOI/xRIOI0xRIOI1xRIOI2xRIOI3xRIOI4xRIOI5xRIOI6xRIOI7xRIOI8xRIOI9xRIOI:xRIOI;xRIOIxRIOI?xRIOI@xRIOIAxRIOIBxRIOICxRIOIDxRIOIExRIOIFxRIOIGxRIOIHxRIOIIxRIOIJxRIOIKxRIOILxRIOIMxRIOINxRIOIOxRIOIPxRIOIQxRIOIRxRIOISxRIOITxRIOIUxRIOIVxRIOIWxRIOIXxRIOIYxRIOIZxRIOI[xRIOI\xRIOI]xRIOI^xRIOI_xRIOI`xRIOIaxRIOIbxRIOIcxRIOIdxRIOIexRIOIfxRIOIgxRIOIhxRIOIixRIOIjxRIOIkxRIOIlxRIOImxRIOInxRIOIoxRIOIpxRIOIqxRIOIrxRIOIsxRInRIrNbuttonN create_target/ RIqNsectionn/D RIpN subsectionn.˜.RIoN subsectionn.) RInN subsectionn-{RImN subsectionn,ƒRIlNsectionn,qRIkN subsectionn+ÌARIjN subsectionn*Ù4RIiN subsectionn*2-RIhNsectionn*(RIgN subsubsectionN link:menu)vRIfN subsubsectionN port:menu'ƒRIeN subsubsectionNbehaviour_component:menu&W RIdN subsubsectionN target:menu"ïRIcN subsubsectionNbehaviour_model:menu!RIbN subsectionn öRIaNboldn DRI`Nboldn RI_Nboldn¬RI^NboldnvRI]Nboldnë RI\Nboldn{ RI[N subsubsectionnÂRIZNboldn¦RIYNboldnRIXN emphasizeNreloadæRIWNboldn† RIVNbuttonNbluffers_guide*RIUN subsubsectionN main:fileñRITN subsectionnÌ#RISNsectionnµRIRNbuttonNreload£RIQNboldnÐRIPNboldn+RIONboldn"RINNsectionnÒ%RIMNexamplenŽBRILNboldnr RIKNexamplen/+RIJNboldnºRIINboldn RIHNboldn†RIGN subsubsectionNhellod RIFNboldnH RIENboldn'RIDNboldn¶ RICNboldnvRIBN subsubsectionn: RIANboldn$RI@NboldnÙRI?NboldnžRI>Nboldn€RI=NboldnwRI Hello World'). 2.2.2. Creating the UI objects After creating the target window, UI-objects may be added to the target-window by dragging them from the UI-object palette. Using `drag-and-drop', UI-objects may be copied between target-windows. Tip: you can define a scratch target-window as a clipboard. Objects may be added to the target-window in any mode. 2.2.3. Modifying UI-objects UI-objects are modified by setting the dialog editor in `create' mode and left-double-click on the item to be modified. This will pop-up an attribute editor. Changes made in this editor are immediate. 2.2.4. Resizing UI-objects Some UI-objects may be resized (button, list and editor). Resizing UI-objects is done by dragging a side or corner using the left-mouse button. 2.2.5. Defining the layout To define the layout, place the objects at their suitable position using the left-mouse. Next, choose `layout' mode and press the `layout' button. This will try to realise the layout you specified using XPCE's symbolic layout mechanism. If you are dissatisfied by the result, the button `undo layout' restores the state to before you pressed the `layout' button. You can fix detailed alignment by double-clicking on a UI-object in `layout' mode and editing the position of the reference-point. After finishing the layout, the `fit' button makes the size of the dialog window fit its contents. 2.2.6. Defining behaviour The behaviour of the dialog is defined by selecting `action' mode and opening the `Behaviour Model'. UI-objects for which you like to define behaviour should be dragged to the Behaviour Model window, where they will be transformed into Behaviour Components. Actions are defined by linking event-ports to send-ports with optional argument links. Consider a dialog with a text-item for `name', a slider for `confidence' and a button for `ok'. Pressing `ok' should call the Prolog predicate assert_confidence/2 with the values of the text_item and slider. To define this behaviour the following steps should be caried out: 1) Drag the text-item, slider and button from the target-window to the behaviour model. 2) Add @prolog from the behaviour-model backgrond menu. 3) Add a `send-port' called `assert_confidence' to @prolog. 4) Link the message port from the button to assert_confidence by dragging with the left-mouse-button 5) Link the selection-ports from the name and confidence objects to the middle of the just created activation-link. 6) Start PceEmacs in Prolog mode on a file. For example by typing ?- emacs('mydialog.pl'). 7) Drag the assert_confidence port to the Emacs buffer. Dropping the port will create a definition template for the predicate. Fill the contents of the predicate, save and compile the buffer. 2.2.7. Simulating the behaviour Put the dialog-editor in `run-mode'. Now just operate the dialog-window. You switch the animation-mode using the dialog at the top of the Behaviour Model editor. You can simulate parts by using the `simulate' entry from the various popup-menus in the model. 2.2.8. Generating Prolog source Drag the dialog from the `Dialog Windows' list to a PceEmacs window running in Prolog mode and drop it there to generate the source. The result is a fact of the form dialog(DialogIdentifier, Description-term). You can now add small main-program as follows: my_program :- make_dialog(D, DialogIdentifier), send(D, open). 3. Loading and saving editor results The current implementation allows you to save and load your edited dialog windows in a format suitable for later editing using the menu-entries from the `File' menu in the main editor. The data is stored in XPCE's internal saved-object format (see `object ->save_in_file' and `file <-object'). This save format satisfies for fast saving and loading, but is not very robust to future changes in the editor format. See also `Reload From Id' 4. Overview of menus 4.1. The dialog-editor main window 4.1.1. The `File' menu # help Jump to this entry # Bluffers Guide Short introductionary text on using this tool. # New Dialog Create a new target window. This is the first step in creating a dialog window. Prompts for the name. # Reload From Id Prompts for identifier of the (loaded) source of a dialog window and attempts to restart the editor from this reloaded source. The current implementation is not successful on all dialog-windows that can be generated using the editor. # Load Load an earlier saved dialog window from file # Save Save the selected dialog window to a file in a format readable by `load'. # Save As Save the selected dialog in the named file. Default file is the name of the dialog with extension '.dia'. # PostScript As Dump a PostScript (tm) representation of the dialog in prompted-for file. The dialog must be opened and completely visible. # Quit Quit the dialog tool. This does not save any changes made. 4.1.2. The `mode' menu The mode menu dictates the interpretation of mouse and typing activity in the target window: # Create Middle-drag moves UI-objects. Double-left-click opens attribute editor on UI-object or for the target-window when clicked on the background. # Layout Shows the `reference' points of the UI-objects. Double-click opens an attribute editor with attributes for handling the layout. Middle drag still moves UI-objects. In this mode, the button `layout' guesses the symbolic layout representation from the window. The button `fit' fixes the size of the dialog to fit its content. # Action Makes the `Behaviour Model' button visible. Clicking on this button will show/create the behaviour-model view. # Run The target-window behaves the same as the generated result will. 4.2. The Behaviour Model 4.2.1. Main menu # PostScript As Generate PostScript (tm) representation of the behaviour model in prompted-for file. The diagram needs not be (entirely) visible. # Destroy Destroy the behaviour model. Using the `Behaviour Model' button on the main dialog editor window you can create a new one. (see mode `action'). # Quit Just quit the editor. The model itself is not destroyed and may be redisplayed using the `Behaviour Model' button in the main dialog. 4.2.2. Background menu # Add Object Add just any object or one of the standard objects from the pullright menu. If `just any' object is used, you have to specify the object in Prolog syntax (e.g. @my_database, class(string), etc.). # Add Constant Similar to Add Object. A constant is a simple object. They too are parsed using the Prolog parser. Thus, an atom constant that requires quotes according to the Prolog syntax must be quoted. # Add Code Adds a standard executable object, normally used as a condition. If you are more experienced you can use this for simple program constructs such as branches, loops, etc. # Add Send/Get/Event Port Add port to the target window as a whole. # Add Init Port Add port called at initialisation of the target window. # Documentation Jump to the XPCE online manual for the class of the target window. 4.2.3. Behaviour Component Menu # Add Send/Get/Event Port Add port of indicated type. See glossary for details. # Documentation Jump to the XPCE online manual for the class or global object. # Edit Edit (like editpce/1) the class of the object. # Cut Delete the object from the model. 4.2.4. Port Menu # Expand (get-port only). Create a Behaviour Component for the value returned by this port and an `expansion-link' from the port to the new Component. # Simulate (event-port only). Simulate the behaviour associated with this port. This has the same effect as putting the target window in `run' mode and activating the UI-object. # Documentation/Edit View XPCE online manual or editpce/1 the represented method or variable. # Cut Delete the port from the object. 4.2.5. Link menu # Simulate Run the send- or get- operation and visualise the result. # Cut Delete the link. Note that any links to/from this link will be deleted to. 5. Bugs 5.1. Menu items can not refer to themselfves It is currently impossible for the message of a menu-item to refer to the item itself or any other menu-item instance. 5.2. Automatic layout generation is very incomplete The `layout' button to guess the intended layout relations from what the user configured is still very incomplete and may move your items to a place where you definitely didn't want them. 5.3. Dragging lists and editors does not work on colour displays This is a problem in translating coloured pixmaps into bitmaps. Must be solved in XPCE itself. 6. Further work 6.1. Grouping of dialog items The current versions lacks the possibility of grouping dialog items. Grouping may be used to define more complex dialog items and to extend the possibilities of the automatic layout system for XPCE dialog windows. 6.2. Include menu-bars At the moment the only alternative is a row of buttons with popup-menus. Note that using the OpenLook default settings this looks the same anyway. 6.3. Include arbitrary graphics This implies first of all getting gestures under the `event-port' paradigm. 6.4. Include the layout of windows in a frame Defining window layout is a hazerdous area for many newbies to XPCE. Direct manipulation techniques could simplify that. 7. Glossary # target-window The dialog window you are defining. A new target window is created using the menu-entry `File/New Dialog' from the editor's main window. # UI-object Visible component on the target window. # Behaviour Model Model of the dynamic behaviour of the target window and its UI-objects. Created using the button `Behaviour Model' which is visible in the `Action Mode'. # Behaviour Component Component of the `Behaviour Model'. This is either a representation of a UI-object or any other XPCE object (e.g. @prolog). A Behaviour Component has a name and `ports' to provide access to its behaviour. A Behaviour Component can also be the expansion of a get-port. # Constant Constant value which may be linked using an argument-link to any operation. # port Access port to the behaviour of a Behaviour Component. When a Behaviour Component is created some almost-always used ports are automatically added. Other commonly used ports may be added using the popup-menu of the Behaviour Component. Ports for any method on the object may be added by dragging a method from the online manual to the port or adding an `empty' port using the popu-menu and typing the name of the method. There are three types of ports: send-port, get-port and event-port. # event-port Represents a starting-point for a sequence of actions. An event-port is triggered on a predefined action on the UI-object. For example, the `message' event-port of a button is executed if the user depresses the button. In the XPCE sence, an event-port is an instance variable of type `code' that is activated when some class-defined `event' occurs. # send-port Represents an action to be caried out by the object. A send port on @prolog represents a predicate to to called. An send-port may be linked to an event-port, stating that the action should be caried out if the event happens. See activation-link. In the XPCE sence, a send-port represents a send-method or a variable with write access. Note that a send-method on @prolog is a predicate. # get-port Represents a value that can be used as an argument to another operation. The result of a get-port is added as an argument of an other operation by linking the get-port to the middle of the target operation. As a get-port generally evaluates to an XPCE object that defines other operations, a get-port may be expanded. New ports may be defined on the expansion. # Activation-link Link between a event-port and a send-port. It indicates that `if this event happens, activate this operation. Argument-links may be attached to the middle of this link. From the middle of this link a condition-link may be attached to any send-port. If multiple activation links are associated to the same event-port, they are executed in the order they are defined. Failing of any of the operations cancels the execution of the event-port. # Argument-link Link between a get-port and any other link. It denotes an argument to the `get-' or `send-' operation expressed by the link. Arguments are numbered 1 ... The argument number may be edited and/or replaced by a name to access arguments by name. # Condition-link Link between an activation-link and a send-port. The condition is executed as the first step of execution the activation-link. If the condition fails, the activation-link is not executed. # Expansion-link An expansion-link is a link from a get-port to Behaviour Component. It may be used to access methods on the object returned by a executing a get-port. x