Eloquence JDLG 1.5 ================== Revision: 2009-07-24 Thank you for your interest in the Eloquence JDLG development. This Eloquence JDLG release provides a development snapshot of the upcoming Eloquence JDLG 1.5 release. By making the development versions available publicly we hope to encourage wider testing. Please contact support@marxmeier.com to share your feedback or report a problem. Please refer to the sections "Recent changes" and "Known issues" at the end of this document for a list of recent changes and known issues and limitations. Please note: This release is available under the terms of the Eloquence Beta Test Agreement which is specified in the file AGREEMENT: http://eloquence.marxmeier/eloquence/download/jdlg/1.5_test/AGREEMENT Downloading and installing the software indicates your agreement to the Beta Test terms and conditions. This beta release may not meet the release criteria for quality or performance and is only intended for test usage. If it breaks you get to keep the pieces. Enhancement Summary ------------------- JDLG 1.5 adds the splitter and tree controls and enhances the groupbox control to support scrolling. It also adds support for context specific popup menus. Configuration changes --------------------- The following new configuration options are supported: eloquence.config.sessionview.quitonclose If set to true (the default) the close button of the JDLG console window will exit JDLG. If set to false, the close button will minimize the JDLG console window. This option is only effective if a tray icon is active. Otherwise, the windows close button will always exist JDLG. Application config file enhancements ------------------------------------ The parser of the application config file was replaced. This simplifies configuration changes and also in addition supports using an "INI" config file format as an option. The new parser is fully backwards compatible and accepts either format. The following section describes the enhancements: - The order of applications listed in the JDLG console window is now equivalent to the order in the application configuration file. - The syntax of the .parameter and .environment keywords in the application configuration file was simplified. It is no longer required to provide a sequence number (for example .parameter.0 .parameter.1 etc.). The .parameter and .environment values are read in the order they are specified in the configuration file. The numbering is ignored and may be omitted. The example below defines the environment variables HOME and DRIVER: APPL.environment = HOME=/home/$login APPL.environment = DRIVER=$host:$port The sequence number of the parameters (for example, APP.environment.1) is no longer required. However, if the sequence number is omitted the specified .parameter value is parsed as a list of entries, separated by spaces. The usual command line quoting rules apply. The example below defines a command line consisting of the -dlg option and the program to be execxuted. The line specifying the -log option may be uncommented without renumbering the remaining .parameter lines. APPL.parameter = -dlg $host:$port #APPL.parameter = -log "C:\Temporary Files\eq.log" APPL.parameter = PROGRAM,VOLUME As the log file name contains a space it must be quoted here (single or double quotes may be used). The .command keyword may now be used as a synonym for .parameter. For example: APPL.command = -dlg $host:$port PROGRAM,VOLUME - The INI file format may be used for the application configuration file as an option. Please note that this requires that the whole configuration file follows the INI file format. It is not possible to mix the original configuration file format with the INI format. For example: # The first application [APP1] name = Application 1 server = 192.168.77.88 protocol = rdlg command = APP1,APPS # The second application [APP2] name = Application 2 server = 192.168.77.88 protocol = rdlg command = APP2,APPS Context menus ------------- By specifying a context menu for an object (or a parent object) a popup menu may be opened with the right mouse button. New attributes: contextmenu, string, get/set specifies the path to a MENU object (in the current dialog or a model) that is opened at the mouse position when the right mouse button is pressed. The .contextmenu attribute specifies the path of a menu object in either the current or another dialog (for example, a model). It is only validated when opening the popup menu. An invalid value has no effect. The .contextmenu attribute is available for all object types. Pressing the right mouse button does not change the focus object. When selecting an entry in the context menu that specifies a rule value other than zero, DLG DO will return with this rule value and the path to the object under the mouse cursor when the popup menu was opened. If the selected menu item has a zero rule value, DLG DO will not return. Any change in the status of a menuitem (eg checked, or radio item selected) is kept. When pressing the right mouse button, the following behavior applies: - If the dialog has a nonzero .rmbr value the DLG DO returns with this rule value. The returned path specifies the object under the mouse cursor when the right mouse button was pressed. - If the object under the mouse cursor specifies a .contextmenu the context menu is opened. When the popup menu is completed the DLG DO may return, depending on the selected menu item. - If the object under the mouse cursor does not specify a .contextmenu the further behavior depends on the object type. - For EditText or ComboBox objects the edit context menu is opened. - Otherwise the parent objects are inquired if a .contextmenu is specified. - The right mouse button is ignored if neither .rmbr nor a associated .contextmenu could be found. Dialog Control -------------- new attributes: margin: integer get/set If set to a nonzero value, a half cell margin is assumed for any children in the dialog. The default value is zero. minheight: integer get/set The minheight attribute may be used to specify a minmal height of a dialog. This is only effective if the dialog is set to the "layout" resizepolicy. minwidth: integer get/set The minwidth attribute may be used to specify a minmal width of a dialog. This is only effective if the dialog is set to the "layout" resizepolicy. Groupbox Control ---------------- A groupbox may have a virtual size that may exceed the visible size. If defined, scroll bars are provided as needed. This allows using the groupbox control to implement dialog elements that exceed the dialog size, for example a variable list of fields. new attributes: vheight: integer, get/set Virtual height of the dialog. If it exceeds the visible height a scroll bar is provided. The default vheight is zero. vwidth: integer, get/set Virtual width of the dialog. If it exceeds the visible width a scroll bar is provided. The default vwidth is zero. margin: integer get/set If set to a nonzero value, a half cell margin is assumed for any children in the groupbox. The default value is zero. Example programs: TABLE Pushbutton Control ------------------ new attributes: focuscolor: string, get/set The focuscolor attribute may be used to specify the background color of a push button that has the keyboard focus. Atom attribute (system and application object) ---------------------------------------------- The atom attribute may be used to save application key/data value pairs in JDLG. This attribute is supported for the system and application objects. Values stored in the system.atom attribute are accessible to all applications connected to the same JDLG process and stay in memory until the JDLG process ends. Values stored in the application.atom attribute are only accessible to the application session. An empty string is returned if no associated key is present. To remove a key/value pair, the key may be set to an empty string. For example: DLG GET "system.atom[sample]",Value$ IF LEN(Value$) THEN PRINT "sample atom is present." ELSE PRINT "sample atom is not present" DLG SET "system.atom[sample]","TIME="&TIME$ END IF PRINT "value=";Value$ Splitter Control ---------------- The splitter control is a layout element that contains exactly two objects of type groupbox or splitter and offers user-controlled resizing of its elements. The splitting may be vertical or horizontal. class name: splitter attributes: orientation: integer, get/set 0 = vertical (default), 1 = horizontal quickexpand: integer, get/set 0 = no buttons (default), 1 = show buttons position: integer, get/set relative position of the divider in size units Notes: - The size of an embedded group box or splitter is ignored and it is resized as needed. A virtual size may be defined for a group box, it is then scrollable if insufficient space is available. - The border attribute of the embedded group box is ignored and no border is drawn. - The splitter control does not get the keyboard focus. Example programs: SPLITTER TREE3 Tree Control ------------ The tree control may be used to display hierarchical data. There are two types of entries, "nodes" that may contain dependent entries ("children") and "leaves" that do not. Entries may be added dynamically (when opening a node). The tree content is internally maintained as a linear list. A leaf entry is immediately ordered below its parent node. Nodes may be empty and return an event when opened. This allows an application to dynamically fill the tree content as needed. The line, add and ins attributes expect an entry definition as an argument. It has multiple fields, separated by the character defined with the delim attribute. {level}[+-] | Text [ | UDATA ] The | character represents the delimiter character. It is used to separate different fields. The level field is an integer specifying the indention level of this entry. Higher indention levels designate a dependent ("child") entry. After the indention level, a + or - character may be present. A "+" indicates the entry is a node and should default to an expanded state. A "-" indicates a node entry that is displayed collapsed (the default for a node). By default, an entry that has no dependent entries ("children") is considered a leaf. An entry that has dependent entries is considered a node. The Text field specfies the text of the entry. It may use HTML content. If present, the udata field defines the udata attribute of the entry. If not present the udata value is unchanged. class name: tree attributes: delim, string, get/set separates different fields in a line defaults to the TAB character add, string, set The add attribute adds a new entry to the tree (at the end). Multiple entries may be added, using an array or separated by a LF character. The first field in the argument specifies the indention level of the new tree entry. If it is greater than the previous entry a dependent entry is added. add[n], string, set The add[n] attribute adds a new entry relative to the node specified by n. If n is zero it behaves the same as the add attribute and adds a new entry at the end of the tree. If n is nonzero a new entry is added relatively to the designated node. The first field in the argument specifies the indention level of the new tree entry. If it is greater than 1 a dependent entry is added. content, string, get/set obtain tree content or replace tree content cy, integer, get/set cy represents the index (1-based) of the "current" entry in the tree. It is set implicitly when an event is returned (like opening an empty node or selecting an entry). Otherwise it indicates the currently selected entry. clear, integer, set The clear attribute is used to reset the content of the tree. The argument is ignored. activeline, integer, get/set The activeline attribute represents the currently selected node or leaf. A zero value indicates no entry is selected. Please note that DLG SET activeline automatically expands any parent node of the selected node or leaf on the next DLG DO or DLG DRAW. line, string, get/set The line attribute may be used to access the "current" entry in the tree. When setting data it may be used to change the text and the udata value (the first field is ignored). When obtaining data, only the first and second fields are returned. line[n], string, get/set The line[n] attribute may be used to obtain or change the designated element in the tree. If n is zero, it behaves the same as the line attribute. lines, integer, get returns the current number of lines open, integer, get/set The open attribute may be used to change the expansion state of the "current" node or obtain its state. A zero indicates to close the node, 1 opens a node. For empty nodes or leaves a zero is assumed. open[n], integer, get/set The open[n] attribute may be used to change the expansion state of the designated node or obtain its state. If n is zero, it behaves the same as the open attribute. openall, integer, set The openall attribute may be used to expand or collapse all expandable/collapsable nodes in the tree at once. Specify a nonzero argument to expand all nodes or a zero argument to collapse all nodes. Please note that this attribute behaves in a special way until the tree has been displayed for the first time. In this case, the openall status is marked for delayed execution on the first DLG DO or DLG DRAW. This has the following implications: If used with a nonzero argument, any subsequent DLG SET open will reset the saved openall status. If used with a zero argument (collapse all), subsequent DLG SET open,1 invocations are also marked for delayed execution. This way it is possible to collapse all nodes and then expand selected nodes before the tree is displayed for the first time. children, integer, get The children attribute may be used to obtain the number of dependent entries of a node. A zero indicates an empty node or a leaf. Plese note that this attribute is only updated on a DLG DO or DLG DRAW operation. children[n], integer, get The children[n] attribute may be used to obtain the number of dependent entries of the designated node. If n is zero it behaves the same as the children attribute. ins[n], string, set The ins[n] attribute may be used to insert new entries in the tree before the designated element. The indention level in the first field is ignored. n may not be zero. rule, integer, get/set The rule attribute specifies the rule to be returned when an entry is selected. If set to zero (the default) the event is ignored. If set to a nonzero value this causes a DLG DO operation to return when a user clicks a node or leaf so that it is selected. The cy and activeline attributes are set. emptynode, integer, get/set The emptynode attribute specifies the rule to be returned when an empty node is opened. If set to zero (the default) the event is ignored. If set to a nonzero value, this causes a DLG DO operation to return when a user tries to open an empty node. The cy attribute is set. udata, integer/string, get/set The udata attribute may be used to obtain or set the udata field of the "current" entry in the tree. udata[n], integer/string, get/set The udata[n] attribute may be used to obtain or set the udata field of the designated element in the tree. If n is zero it behaves the same as the udata attribute. del, integer, set The del attribute may be used to delete the "current" entry from the tree. The argument specifies the number of entries to delete. If the argument is zero all elements of the current indention level are deleted. If a node is deleted, all dependent entries are also deleted. del[n] The del attribute may be used to delete the designated entry from the tree. If n is zero it behaves the same as the del attribute. The argument specifies the number of entries to delete. If a node is deleted all dependent entries are also deleted. parent, integer, get The parent attribute may be used to obtain the index of the parent node (1-based). A zero indicates a node has no parent. Plese note that this attribute is only updated on a DLG DO or DLG DRAW operation. parent[n], integer, get The parent[n] attribute may be used to obtain the index of the parent node of the designated node (1-based). If n is zero it behaves the same as the parent attribute. useicons, integer, get/set The useicons attribute specifies whether the default icons for a node or leaf are displayed. A zero value causes the icons to not be displayed. The default is 1. Example programs: TREE2 TREE3 Recent changes -------------- Changes since 2009-07-23: - tree: Fixed a problem with DLG SET .open,0 and .openall,0 where the activeline was not updated. This could cause the previous activeline to become expanded again on the next DLG DO or DLG DRAW. Changes since 2009-07-22: - tree: Fixed DLG SET .activeline which could affect the wrong tree item. - tree: FIXED DLG SET .open on leaf items which wrongly affected the parent node (and this way could also affect the invisible root node). - tree: Fixed general rule handling. DLG SET .open,0 and DLG SET .openall,0 no longer issue any rule. Changes since 2009-05-27: - A problem with maximized windows was fixed. If a dialog is initially opened in maximized state, the dialog contents were not correctly resized under certain conditions. - htmlview: The .rule and .mimetype attributes were not correctly cloned from a model. - progressbar: After a DLG SET .text the modified progressbar text was not immediately displayed (#3822). - Fixed a ClassCastException which could occur if the format of a sessions configuration file could not be recognized. - tree: Fixed an IndexOutOfBoundsException which could occur with DLG GET line[n] or DLG GET open[n] under certain conditions. - tree: The .lines and .openall attributes were added. For details, please refer to the tree attribute documentation above. Changes since 2009-05-26: - splitter: Fixed a potential problem with the max. splitter position when the containing object is not a multiple of the raster position (#3783, revision of the 2009-05-07 fix). Changes since 2009-05-07: - Using DLG SET or DLG GET with an object path containing a wildcard pattern could affect the wrong objects. Changes since 2009-04-30: - tree: Fixed a problem with the tree control not correctly copying its attributes when used in a model. - tree: Fixed a problem with the tree control not returning recent changes (using .line or .content attributes) until the next redraw. - Fixed a potential layout problem with maximized windows when using the "layout" resize policy. - splitter: Fixed a potential problem with the max. splitter position when the containing object is not a multiple of the raster position. - listbox: Fixed a problem with single column listboxes that could result in an exception as below when clicked. Exception in thread "AWT-EventQueue-0" java.lang.Arra IndexOutOfBoundsException: 1 >= 1 at java.util.Vector.elementAt at javax.swing.table.DefaultTableColumnModel.getColumn at javax.swing.JTable.convertColumnIndexToModel at com.eloquence.services.jdlg.controls.EListBox.mouseReleased Changes since 2009-04-23: - Fixed rounding problem with maximum splitter position in tab panes. The splitter position is rounded down towards the next raster boundary. This could be a problem when a splitter is in its maximum position and the size was not a multiple of a raster size. - Fixed a potential problem with positioned POPUP boxes and reference point. - Fixed a problem with large window sizes on Windows. When using a single screen JDLG tries to assure the Window is entirely visible. A problem was fixed that could result result in improperly ignoring or accountng twice for the space occupied by the Windows task bar. Changes since 2009-04-21: - Add support for Windows Vista frame insets - Fixed a problem with focuscolor on a pushbutton not correctly restoring the previous background color when the groupbox or dialog had a background color defined. - Fixed a problem that could cause unexpected collapsing of open tree objects on DLG DO or DLG DRAW. Changes since 2009-04-15: - Fixed a problem with context menus in an empty list box not working as expected. - listbox: Fixed a problem with sorting of negative numeric values and numeric entries using HTML formatting. - The POPUP BOX object was enhanced to use a reference point. - A problem with maximized windows was fixed. If resizable and non-resizable dialogs were used the maximized attribute was not correctly inherited. - A Listbox object within an insensitive groupbox could be modified even if the server was busy. - A default mouse cursor was used for text fields instead of a text cursor. - Fixed a problem with ComboBox tab handling. - Added network diagnostic log messages if the connection was aborted or closed unexpectedly. - tree: Fixed possible truncation problem when switching icons on for previously opened elements. The tree is now collapsed if the use of icons is changed. Changes since 2009-03-16: - tree: Fixed possible exception when adding empty string - Fixed limitation with multiple screens on windows. When multiple screens are present on Windows, the window position is no longer restricted to the current screen. Previous JDLG versions required that at least a part of a dialog is visible on the main screen. - Added system.multiscreen attribute. This returns a nonzero value if multiple screens are detected. - Added system.dlgport attribute. This returns the current port number used by JDLG to listen for new connections. By default the port number 8011 is used. However, when configured to zero a dynamic port number is used. This value was previously available by accessing the undocumented attribute system.dlgsrv. - html content in application.name (application list) does not work as expected when no icon is shown Changes since 2009-03-12: - Fixed problem in Listbox and Combobox objects with the .line attribute returning error 657 - Fixed login problem caused by a side effect of the new application config file parser. Changes since 2009-02-26: - Added minwidth and minheight attributes for dialog. This may be used to specify a minimum size of a dialog when using the resizepolicy "layout". - Added support for focuscolor attribute for pushbutton objects. If set, this may be used to specify the background color of a push button that has the keyboard focus. - Added atom attribute to the system and application objects. This attribute may be used to save application key/data combinations in JDLG. Values stored in the system.atom attribute are accessible to all applications and stay in memory until JDLG ends. Values in the application.atom attribute are only accessible to the application session. - Fixed bug in splitter control that could cause resetting the splitter position. - Fixed an internal exception as below when accessing an invalid rowdata attribute of a poptext object. java.lang.ArrayIndexOutOfBoundsException: -1 at java.util.Vector.get at com.eloquence.services.jdlg.controls.EPopText.getRowData - Added option to set system.atom key/value pairs through the configuration file (or java commandline). The following example defines the system.atom key "sample" with the value "Hello World". eloquence.config.atom.sample = Hello World - Replaced application config file parser. This allows additonal flexibility and the alternative use of an "ini" file style format instead of a JAVA property format. - Applications defined in the application config file appear in the file order. Previous versions ordered applications by name. - Improve validation of array attributes for tree obejct. - More selective internal copying of java states to JDLG attributes. This fixes some corner cases and may provide a minor improvement for DLG DO returning to the application after an event. Changes since 2009-02-13: - Added .contextmenu attribute to support popup menu functionality - Fixed a groupbox layout problem when hoizontal scrollbar is visible - Fixed a layout problem for nested groupboxes with borders that could result in groupbox broders to become partially invisible - Fixed a JAVA exception when attemting to access invalid udata entries in a tree object Changes since 2009-02-06: - dialog: Added new margin attribute that results in a half cell margin to child objects. - groupbox: Added new margin attribute that results in a half cell margin to child objects. - tree: The default udata attribute returns an empty string. Previously, an integer value of zero was returned. This default is now consistent with other objects. - splitter: Fixed a problem with wildcards and splitter. Wildcards did not work on objects in a splitter control. - tree: Fixed a JAVA exception on accessing invalid udata entries. - listbox: Fixed a JAVA exception with scroll bars. Changes since 2009-01-28: - tree: Fixed problem with focus change using TAB key - Improved performance on DLG DO when a huge number of edittext or combobox objects are used - Fixed a problem expanding environment variables in the application config file - Fixed a layout issue with toolsbars when scaling a dialog - tree: Fix possible exception with .add after .clear Changes since 2009-01-15: - Handling of the GroupBox scroll bars was improved. - Added the eloquence.config.sessionview.quitonclose property to cause the console close botton have the same effect as the minimize button if a tray panel is available (set to false for this function). - The visibility of the console Window may not be toggled by clicking on the tray icon (if available) - Fixed a layout issue with the status bar - Fixed postential stack overflow when a huge number of non-focussable objects is present in a dialog Changes since 2008-12-19: - Fixed various problems with tree control - tree: fixed set .line and .ins - tree: implemented correct rule behavior Known issues ------------ - Some example programs use OS dependent system calls and were only tested on Linux - The Mouse cursor may not change in listbox header in some cases. - Moving a dialog as it is violating the screen boundaries may change the reference point - Space used by the desktop task bar or menu bar is not properly accounted for in JDLG on the linux platform. This is caused by a JAVA/Swing limitation that does not provide this information. This should have little consequences besides JDLG cannot ensure a window is not obscured by desktop elements.