Best Practice - Programming Ribbons

Size: px

Start display at page:

Download "Best Practice - Programming Ribbons"

Charlene Eaton
6 years ago
Views:

1 Best Practice - Programming Ribbons

2 Copyright 2016 Lexmark. All rights reserved. Lexmark is a trademark of Lexmark International, Inc., registered in the U.S. and/or other countries. All other trademarks are the property of their respective owners. No part of this publication may be reproduced, stored, or transmitted in any form without the prior written permission of Lexmark.

3 Table of Contents 1 Introduction Ribbon Structure Functional Description Events Managing Controls using Events Creating Ribbon Elements Creating Tabs Creating Groups Creating Controls Control Types Universal Properties... 5 BeginGroup... 5 Enabled... 6 IconId... 6 Style... 6 TooltipText... 6 Visible... 6 Text... 7 Width Extending Controls with Icons Embedding the Controls in the Quick Access Bar Sample Macro"ribbon.bas" Extensions Loading Ribbon Icons out of Ressource Appendix s SAPERION Main Menu "Start" Menu "Folders" Menu "Import" Menu "Advanced" Menu "Design" Menu "Administration" Menu "Document Tray" Menu "Edit" Menu... 14

Best Practice - Programming Ribbons 1 Introduction The ribbons introduced in SAPERION 7 are based on third-party programs from Codejock Software. They are provided as ActiveX objects (Codejock.*.

4 Best Practice - Programming Ribbons 1 Introduction The ribbons introduced in SAPERION 7 are based on third-party programs from Codejock Software. They are provided as ActiveX objects (Codejock.*.ocx; in the SAPERION directory). The API interface allows you to create and display your own ribbons. The procedure described below describes the best practice for programming ribbons. 2 Ribbon Structure The ribbon consists of tabs, groups and various controls that are designed task-orientated and in accordance with particular application scenarios. This means that only certain groups of controls are relevant when objects of certain types are processed. Fig. 2 1: Ribbon Structure A ribbon contains normally the following elements: Quick Access Toolbar The quick access toolbar can be individually configured and includes for instance commonly used commands. Tabs Tabs add structure for the ribbon groups, and can contain only groups. Groups Groups are used to structure the ribbon controls, and can contain only controls. Controls Each control is assigned to a particular ribbon group. Each element in a ribbon has a defined ID.! Please keep in mind that you have to assign ribbon IDs for elements in the ribbon which you create yourself and that a scope of IDs greater than 50,000 has been allotted for this purpose. 1

5 3 3 Functional Description 3.1 Events Functional Description For certain functions to be executed when a ribbon control is pressed in the Rich Client, a corresponding callback must be implemented. A callback is a function whose name is established when the menu object is created. Using the cmdid one can define which action takes place. The cmdid corresponds to the ID of the verified ribbon control. Example Sub CallbackName( cmdid As Long, cmdstring As String, ocurrmask As Object ) Select Case cmdid Case ControlId MsgBox "Control: " & CStr(cmdId) & "was pressed!" Case Else MsgBox "Unknown command Id : " & CStr(cmdId) & "!" End Select End Sub 3.2 i Managing Controls using Events With SAPERION 7.1 SP4, all ribbon handling is controlled by one OnRibbonEvent. Because this is - contrary to the conventional method - much simpler, we recommend to use this event-controlled method from SP4 on. The OnRribbonEvent makes it possible to manage the entire ribbon handling inside of one method, by linking the ribbon event with its own ribbon method. The method has the following standard event API: Example Function OnRibbonEvent( pre As Long, note As String ) As Boolean Pre = 0 : This value has no special meaning note = <form name>.<event name> Define the parameters form name: Name of the currently active form. If there are no active forms, the value "application" is valid. event name: Name of the events (see following table). The following events are used to program ribbons: 2

6 4.1 Creating Tabs OnRibbonEvents Event Description FormCreate Form is created. Depending on the form, this event displays the controls that are valid for form and for the active element in the result list (if there is one). FormSetFocus Form has focus. Depending on the form, this event displays the controls that are valid for form and for the active element in the result list (if there is one). FormKillFocus Form no longer has focus. The controls for the form are deactivated or hidden. FormRefresh Refreshes the results list of a form. The controls for the results list must be deactivated. FormClose The form is closed. The controls for the form are deactivated or hidden. ItemSelect Selects a row in the result list. The controls that are valid for the active element in the results list are activated (depending on the form). RibbonInit The entire ribbon is initialized. All controls that are created are displayed correctly. NOTE: Please validate the context of the form. RibbonCreate The ribbon is created anew. Creates a menu object, and then creates an entry for each ribbon control. In addition, you can expand the ribbon with the desired tabs, groups and controls. 4 Creating Ribbon Elements 4.1 Creating Tabs A tab can be added by means of the following function: Dim otab As Object Set otab = Application.Ribbon.InsertTab( Index, "TabName" ) Set otab = TabID In order to find the tab again later, a unique ID should be assigned to the tab using the property otab.id = TabID. 3

7 4 Creating Ribbon Elements otab = Application.Ribbon.FindTab(TabID) 4.2 Creating Groups You can add a group to an existing SAPERION tab or to a new tab. In both cases the corresponding tab object is needed. There are two possible ways to add a group to a particular tab: Function 1 Set ogroup = otab.groups.addgroup(gruppenname, GruppenID) Use this function to create a group in the last position of the tab. Function 2 Set ogroup = otab.groups.insertgroup(index,gruppenname, GruppenID) Using this function, you can also use the index parameter to control at which location in the tab the new group should be added. 4.3 Creating Controls Ribbon controls can be assigned to any group. The group object is added to the control using the following function: Set octl = ogrp.add(controltyp, ControlID, ControlName, Position) Note that the position parameter is optional Control Types In the following overview all control types used in SAPERION are listed: Control types Control Type Description Button Button control. By clicking the button an event is fired. Popup Control that displays a caption with no image. When clicked, a popup menu will display any added controls. Button Popup Control that displays an image with no caption. When clicked, a popup menu will display any added controls. Split Button Popup Control that consists of a button and a popup. Edit Edit box control. 4

8 4.3 Control Type Description Checkbox Checkbox control. The user can select or deactivate an option. Creating Controls Property Checked (Boolean) Public Property Checked() As Long Combobox Combobox control. The user can open a list of given options and choose one item from the list. Property AutoComplete: De-/ activation of the automatic completion. Public Property AutoComplete() As Boolean Methods AddItem: Adds an item to the combobobox control (string or optionally integer). Public Sub AddItem( _ ByVal Text As String, _#Optional ByVal Index As Variant _) Public Sub AddItem( _ ByVal Text As String, _#Optional ByVal dex As VaClear: Clears the content of the combobox. Public Sub Clear() FindItem: Finds the first item in the combobox that starts with the specified string. Public Function FindItem( _#ByVal Text As String _#) As Long Public Function FindItem( _#ByVal Text As String Text As String RemoveItem: Removes an item from the combobox. Public Sub RemoveItem( _#ByVal nindex As Long _#) Public Sub RemoveItem( _#ByVal nindex As Radiobutton Radiobutton controls are usually grouped so that the user can choose one of multiple options Universal Properties In the following properties are listed that can be used for all controls mentioned above BeginGroup Public Property BeginGroup() As Boolean 5

9 4 Creating Ribbon Elements Adds a separator in front of a control Enabled Public Property Enabled() As Boolean The control is activated (TRUE) resp. deactivated (FALSE) IconId Public Property IconId() As Long Reads/ sets the icon ID of the control. The icon ID allows you to change the icon associated with a control without changing the ID of the control Style Public Property Style() As Long Reads/ sets the style of the control. 0 = automatic display 1 = only the title is displayed 2 = only the icon is displayed 3 = the title and the icon is displayed 4 = the title is displayed under the icon TooltipText Public Property TooltipText() As String Reads/ sets the tooltip text of the control Visible Public Property Visible() As Boolean 6

10 4.3 Creating Controls Defines whether the control is visible (TRUE) Text Public Property Text() As String Reads/ sets the text of the current selection. You are allowed to replace the text by your text Width Public Property Width() As Long Reads/ sets the size (in pixels) of elements Extending Controls with Icons You are allowed to assign an own icon to a control. First add the icon to the internal adminsitration. omen.addicon <IconPath,IconId> Then assign the icon directly to an existing control. octl.iconid = IconId Embedding the Controls in the Quick Access Bar It is also possible to add custom ribbon controls just to the quick access bar. The ribbon controls don't have to already exist in the ribbon. If you intend to add custom ribbon to the quick access toolbar, then use the following function: octl = Application.Ribbon.QuickAccessControls.Add(ControlTyp, ControlID, ControlName, Position) To find controls in the ribbon, use the following function: octl = Application.Ribbon.QuickAccessControls.Find(0, ControlId) 7

11 4 i Creating Ribbon Elements Controls in the quick access bar cannot be found through the "octl = Application.Ribbon.FindControl( 0, ControlId )" function. This will also apply to controls that are added to the ribbon with the same ID. 4.4 Sample Macro"ribbon.bas" During the SAPERION installation, the "ribbon.bas" file is installed by default. The "ribbon.bas" file is copied into "...\Program Files (x86)\saperion\macros" directory. The macro contains examplarily some use cases such as the creation of new tabs, new groups, new controls and icons or controls that are active when a particular form is active and a row is marked in the results list Extensions Following extensions are made by "ribbon.bas": Extending the "Start" tab with controls An extension of the Start tab with the following four controls in an existing group a button that is always active a button that is only active when the form "example71_q" is active a checkbox which is activated and checked when a row in the results list of the "example71_q" form is selected. all elements of the "example71_q" form are hidden when the form is not active. Extending the "Start" tab with a group A new group in the "Start" tab with a button that is active when the "example71_q" form is activated. The group is always visible, even when the form is not active. Adding a new tab A new tab containing a group with a button, after the Start tab. The elements are always visible Loading Ribbon Icons out of Ressource For the loading of ribbon icons it is allowed to point directly to the resource. This means that the path to images no longer needs to be specified. Examples loading an icon out of the resource file omen.addicon "!CustomLightRed16",ICON_BTN_FORM loading the icon "test.png" or "test.bmp" out of the "Image" directory 8

12 5.1 omen.addicon "!Test",ICON_BTN_FORM 5 Appendix 5.1 s SAPERION Main Menu s SAPERION main menu Titel/ Caption 5002 Window Properties 1703 Save Window Position When Closing 1704 Save Window Position Now 1705 Clear Saved Window Position 1706 Edit Caption Reset Layout 1062 Checked-out Documents Print Print Preview 5954 Document(s) 1221 Search Query Log Table From Document Tray Search Query Log Table Settings Settings 1304 OCR System AutoCorrect Manage Stamps 1308 Current User Display Status Bar Records Management 1333 Rules Help 9 s

13 5 Titel/ Caption 1504 Using Help About Switch Current User Close "Start" Menu "Start" menu 2258 Refresh 2259 Reset 1249 Add to Favorites 1241 Export View 5953 Edit Edit Annotations 5955 Index Structure 1060 Check Out 1059 Check In 1061 Discard 5957 Delete 46 Revisions Save As Send 1072 Send Link 1073 Send as Copy 1074 Send Copy and Link 1250 Add Documents to Favorites 1067 Cross-reference 5972 Set Access Lists Start Process Start Adhoc Process Private Templates 5993 Public Templates 3581 History Comments Appendix

14 Reassign Reminder Put Back 3587 Tasks "Folders" Menu "Folders" menu 4308 Refresh 4300 Create Folder 4301 Create Application Create Tray Folder Delete 4305 Access List Classes "Import" Menu "Import" menu 1054 Page Feed Single Page Replace Page Scan Profile 1339 Duplex 1000 File(s) New Page Bulk Import COLD Data Scanned Pages Loaded Files Configuration 1300 Options Format Preset Input 11 s

15 Documents 1052 To Do "Advanced" Menu "Advanced" menu 1218 Create Reader Quality assurance New 1201 Load Save Delete Refresh 1242 Back to Form "Design" Menu "Design" menu 1212 Create Load Edit Save As Delete Document Formats Process Designer Events Scripts Edit Form Create Search Form Create Index Form Print Lists Cover Sheets Appendix

16 Background Forms "Administration" Menu "Administration" menu 1329 New Content Type Edit Content Type New Retention Class Edit Retention Class Encryption 1337 Localization Administration Access Lists Query Form 1226 Configure Forms Settings Export "Document Tray" Menu "Document Tray" menu 2451 Order 2450 Disconnect 2454 Save As 2455 Format 2456 Complete 1076 Send 1206 Add Page 1207 Add All 2460 Up 2461 Down 2459 Right 2458 Left 2453 View 13 s

17 Edit Edit Name 2465 Delete 2477 Delete All 2467 Encrypt 2466 Security 2471 Rendering 1210 Single Document 1211 Index Form All Documents 1233 Options Activate Forms Index Form 1208 Index Automatic Indexing Create Edit Verify 2469 Delete 2473 Finish 2474 Finish All 2475 Start Mass Signing "Edit" Menu "Edit" menu 2013 Previous Document 2054 First Page 2011 Previous Page 2010 Next Page 2055 Last page 2012 Next Document 2005 Zoom In 2006 Zoom Out 2000 Fit 2081 No Auto Scale 14 Appendix

18 Fit to Page 2083 Fit to Whole Page 2048 Enlarge 2049 Reduce 2036 Previous Link 1103 Insert 1101 Cut 1102 Copy 1100 Undo 1104 Delete 2014 Rotate Rotate Rotate Mark All 15 s

Teamcenter 11.1 Systems Engineering and Requirements Management

SIEMENS Teamcenter 11.1 Systems Engineering and Requirements Management Systems Architect/ Requirements Management Project Administrator's Manual REQ00002 U REQ00002 U Project Administrator's Manual 3