create 18.11

git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@2112 abb3cda0-5349-4a8f-a601-0c33ac3a8c38

documentation/18.11/solutions/platform-specifics/microsoft-windows/eiffelribbon/eiffelribbon-design-tool.wiki

@@ -0,0 +1,134 @@
+[[Property:title|EiffelRibbon Design Tool]]
+[[Property:weight|0]]
+[[Property:uuid|E0B7F3F8-F7B1-43C4-8B7E-D175BC9A7D9F]]
+=Overview=
+
+The EiffelRibbon design tool allows you to design a ribbon graphically, then generate the ribbon markup file and the Eiffel classes necessary to implement your design. 
+
+
+[[Image:EiffelRibbon design tool 01|EiffelRibbon design tool]]
+
+Figure 1: An EiffelRibbon project open in the EiffelRibbon design tool.
+
+
+The interface of the design tool mimics that of [[EiffelBuild|EiffelBuild]]. That is, the interface contains three panes that have counterparts in EiffelBuild:
+
+# Type selector: A list of all the elements available for use in a ribbon.
+# Layout constructor: A structured view of the organization of the elements used in a particular ribbon design.
+# Object editor: The properties of the ribbon element which is currently selected in the Layout constructor.
+
+So, if you've used EiffelBuild, the EiffelRibbon design tool should seem quite familiar to you. 
+
+=Usage=
+
+The typical usage of the design tool is much like the typical usage of EiffelBuild. 
+
+* Create a new project ( <code lang="text">File -> New Project...</code> ) and choose a location for your EiffelRibbon project.
+* Configure the ribbon by adding elements, name the elements, and choose icons for buttons.
+* Save the project.
+* Generate the code.
+* Use EiffelStudio to compile the generated code.
+
+==Size definitions and scaling policies==
+
+An important aspect of Microsoft's ribbon technology is called '''[http://msdn.microsoft.com/en-us/library/windows/desktop/dd316927(v=vs.85).aspx adaptive layout]'''. When the ribbon is resized by a user at runtime, the adaptive layout makes corresponding changes to the size, format, organization and scale of the ribbon controls within each group based on size definition templates and scaling policies associated with the group. Size definitions are patterns for the use of a certain number of ribbon controls such as buttons. For a particular group of controls in an instance of ribbon, you can associate a size definition which will control the layout of the controls. At runtime, when the window hosting the ribbon is resized, a scaling policy, also associated with the group, will control how the controls in the group are reorganized in response to the resizing. When a group is selected in the EiffelRibbon tool, the group's size definition and scaling policy can be selected. 
+
+{{note|Not all size definitions support all scaling policy choices. So it is important to know which scaling policies are supported by a size definition that you wish to associate with a group before you set the scaling policy for the group.}}
+
+===Size definitions===
+
+The ribbon framework provides a significant number of size definition templates (simply called '''size definitions'''), as shown in Figure 2 below. Size definitions are usually assigned names based on the number and type of controls included in the group. For example, the size definition ''"ThreeButtonsAndOneCheckBox"'' is a size definition for three buttons plus one checkbox.
+
+
+[[Image:EiffelRibbon Choose Size Definition]]
+
+Figure 2. Choosing a size definition for a ribbon control group.
+
+
+In addition to using the size definitions provided, it is possible to create your own custom size definitions. You do this with the '''Size Definition Editor'''. At the lower left of Figure 1 above you can see the tab representing the Size Definition Editor. When you expand the tab, the editor becomes visible, as in Figure 3, below.
+
+
+[[Image:EiffelRibbon size definition editor|Size Definition Editor]]
+
+Figure 3. EiffelRibbon tool with the Size Definition Editor pinned open.
+
+
+Use the Size Definition Editor to create custom size definitions for your ribbon designs. The '''Add button''' button will add a new button placeholder to a custom size definition. A selected button placeholder can be altered to show or hide its label and use its small or large size. 
+
+
+[[Image:Size Definition Editor 02|Button placeholders]]
+
+Figure 4. Three button placeholders in a custom size definition (highlighted in red rectangle); one is large, and two are small. The text is visible in all cases. (This is the arrangement used for the "medium" configuration (highlighted in green rectangle) for the ''ThreeButtonCustom'' size definition used in the scaling policy figures in the next section.  Screenshots of specifying arrangements used for "large" "small" configurations for ThreeButtonCustom are not shown.)
+
+
+Once a custom size definition has been designed, it can be named, saved, and used in a ribbon design.
+
+
+[[Image:Size Definition Editor 03|Name field and Save button]]
+
+Figure 5. The Size Definition Editor naming field and '''Save''' button.
+
+
+When you generate code which uses a custom size definition, the EiffelRibbon Design Tool generates the (XML) representation for your size definition and then invoke the Microsoft Ribbon Framework's User Interface Command Compiler (UICC.exe) to validate the generated size definition code. This process can result in [http://msdn.microsoft.com/en-us/library/windows/desktop/dd316918(v=VS.85).aspx certain types of errors]. 
+
+User Interface Command Compiler errors will appear in the Output pane of the EiffelRibbon Design Tool.
+
+
+===Scaling policy===
+
+The notion of adaptive layout includes the ability to specify preferred sizes for elements of a group and a scaling policy that can influence how the group reacts to resizing. More detail on size definition and scaling policy is available in Microsoft's [http://msdn.microsoft.com/en-us/library/windows/desktop/dd316927(v=vs.85).aspx ribbon documentation]. 
+
+The EiffelRibbon tool allows you to specify ideal sizes and scale policy for a groups elements through the '''Ideal sizes''' radio buttons and the '''Scale''' checkboxes, as shown in Figure 6 below.
+
+
+[[Image:EiffelRibbon design tool 02|Scaling policy elements: "Ideal sizes" and "Scale"]]
+
+Figure 6. A group definition showing it's size definition and the scaling policy elements "Ideal sizes" and "Scale".
+
+
+In Figure 6, none of the Scale checkboxes is checked. This means that no scaling policy is in effect for the group ''group_context_popups''. So in a running application, a window with this ribbon might be rendered as shown in Figure 7:
+
+
+[[Image:EiffelRibbon scaling policy 01]]
+
+Figure 7. A ribbon with no scaling policy, but with enough room to display all groups.
+
+
+If the user resized the window to a narrower form, the buttons in the ''group_context_popups'' group would become occluded because scaling is not in effect. This is shown in Figure 8.
+
+
+[[Image:EiffelRibbon scaling policy 01a]]
+
+Figure 8. After resizing, some buttons of the group are no longer visible.
+
+
+If all of the ''Scale'' checkboxes that are supported by the size definition are checked in the EiffelRibbon tool for the group ''group_context_popups'' as shown in Figure 9, then scaling is enabled. 
+
+
+[[Image:EiffelRibbon scaling policy 02|Scale checkboxes enable scaling policy.]]
+
+Figure 9. All supported scales are enabled for ''group_context_popups''.
+
+
+In the running application again, the initial rendering looks the same as in Figure 7 (its ''Large'' configuration). But if the window is resized to a narrower form with scaling policy enabled, it will go through the various configurations supported by the size definition: ''Medium'', ''Small'', then ''Popup''. The different configurations for this particular ribbon and size definition are shown in Figures 10 through 12.
+
+
+[[Image:EiffelRibbon scaling policy 03|Medium configuration]]
+
+Figure 10. Scaling policy at medium configuration (see Figure 4 above).
+
+
+
+[[Image:EiffelRibbon scaling policy 04|Small configuration]]
+
+Figure 11. Scaling policy at small configuration.
+
+
+
+[[Image:EiffelRibbon scaling policy 05|Popup configuration]]
+
+Figure 12. Scaling policy at popup configuration.
+
+
+
+

documentation/18.11/solutions/platform-specifics/microsoft-windows/eiffelribbon/index.wiki

@@ -0,0 +1,78 @@
+[[Property:title|EiffelRibbon]]
+[[Property:weight|2]]
+[[Property:uuid|2f24957c-7fdc-f918-8c0d-37a9ef525508]]
+=Introduction=
+
+EiffelRibbon is a library of classes with an associated [[EiffelRibbon Design Tool|tool]] which allows the integration of the Microsoft Windows "Ribbon" into graphical user interfaces programmed with [[EiffelVision 2]] and targeted to Microsoft Windows. The ribbon is part of a [http://msdn.microsoft.com/en-us/library/aa338198.aspx#office2007uifordevelopers_detaileddesignofthenewuisystem revamped user interface approach] introduced by Microsoft with the 2007 release of the Microsoft Office applications. So you've experienced the ribbon if you've used Microsoft Word, PowerPoint, or Excel from 2007 or later. 
+
+
+{{note|''Although EiffelRibbon classes work with EiffelVision 2 which is multi-platform, systems using EiffelRibbon can be targeted only to the Microsoft Windows platform.''}}
+
+
+[[Image:EiffelRibbon window 01|A ribbon on a window]]
+
+Figure 1: A ribbon at the top of a window.
+
+
+The EiffelRibbon library contains the classes that are used to implement the ribbon facilities. The classes in the EiffelRibbon library all have class names beginning "EV_", the default prefix for EiffelVision 2 classes. So the EiffelRibbon classes can be seen as an extension to the EiffelVision 2 library. If you've used EiffelVision 2 to create applications with graphical user interfaces, then the EiffelRibbon class won't look unfamiliar to you. However, unlike other EiffelVision 2 classes, the EiffelRibbon classes only work in applications targeted to Microsoft Windows.
+
+To gain a detailed understanding of the goals of Microsoft's Ribbon technology including some guidelines on designing effective ribbons, see [http://msdn.microsoft.com/en-us/library/cc872782.aspx the '''Ribbons''' page] on Microsoft's MSDN site. 
+
+The [[EiffelRibbon Design Tool|EiffelRibbon design tool]] helps you configure a ribbon in much the same way that [[EiffelBuild|EiffelBuild]] (ES Builder) helps you layout a GUI application.
+
+
+=The EiffelRibbon Library=
+
+The EiffelRibbon library contains the classes necessary to add ribbons to EiffelVision 2 applications. As stated above, you won't really need to use the library directly. Rather, you use the EiffelRibbon tool to build an application that uses the library classes.
+
+Still you may find it interesting to browse the classes in the library. You'll see that as in the EiffelVision 2 library, many of the classes are there to provide support for the various elements that can be used in an application. Most of the class names for EiffelRibbon-specific elements begin with the prefix "<code>EV_RIBBON</code>". Some examples are: <code>EV_RIBBON_BUTTON</code>, <code>EV_RIBBON_DROP_DOWN_GALLERY</code>, and <code>EV_RIBBON_COMBO_BOX_ITEM</code>. Again, similar to EiffelVision 2, the class <code>EV_RIBBON_COMBO_BOX_ITEM</code> models an item for a <code>EV_RIBBON_COMBO_BOX</code>.
+
+So, here again, if you are familiar with EiffelVision 2, then EiffelRibbon should not seem very foreign to you.
+
+
+=EiffelRibbon Applications=
+
+When you build an application with the [[EiffelRibbon Design Tool|EiffelRibbon tool]], it generates classes for you. These classes are often clients or heirs to classes in the EiffelRibbon library. The classes generated for the objects on your ribbon should look familiar to you as well. For example, as with EiffelBuild, for each ribbon object, say a button, there will be a class ending with the suffix "<code>_IMP</code>" which will get regenerated each time you request the EiffelRibbon tool to generate classes. Also generated is an heir to that class with a name that does not include the suffix. This class you are free to edit, as it will not be regenerated. It is in these editable classes that you provide the action sequences for your ribbon objects' behaviors.
+
+The class shown in the Edit pane of EiffelStudio in Figure 2 is a portion of a generated class <code>BUTTON_CHANGE_SMALL_IMAGE</code>, representing a ribbon button, from one of the EiffelRibbon examples. <code>BUTTON_CHANGE_SMALL_IMAGE</code> is a heir to <code>BUTTON_CHANGE_SMALL_IMAGE_IMP</code>. You can see that in the redefined version of <code>create_interface_objects</code> code has been added to add an agent to the <code>select_actions</code> for the ribbon button. In this case, it's an inline agent that will toggle the associated image back and forth between two different images.
+
+
+[[Image:EiffelRibbon application 01|An EiffelRibbon application in EiffelStudio.]]
+
+Figure 2.
+
+==Project '''modes'''==
+
+EiffelRibbon projects can be built in one of two different '''project modes'''. The project mode is selected from the '''Project''' menu of the EiffelRibbon design tool. 
+
+The default mode, called '''DLL mode''', is the most all encompassing project mode. It has the advantage that the full capabilities of EiffelRibbon are accessible. In DLL mode, a separate DLL is created to contain the generated code for each ribbon created for the project. 
+
+The alternative to DLL mode is '''Application mode'''. Application mode allows almost all the capabilities of DLL mode, but includes all ribbon code in the project's executable image (.exe). For this reason, it is necessary to re-freeze the project after changes when using Application mode. Re-freezing is not necessary in DLL mode.
+
+Both modes allow multiple ribbons to be created for multiple windows. However certain restrictions apply in Application mode that do not apply in DLL mode. In DLL mode, different DLL's are created for each ribbon. These DLL's are separate and do not share data. However, in Application mode, a number of ribbon facilities, including the help button, the quick access toolbar, and the mini toolbar, are shared among all the ribbons defined. In DLL mode, these facilities are not shared and as such can be different for each ribbon. 
+
+=Usage notes=
+
+==System requirements==
+
+To use the EiffelRibbon library and tools you must have:
+
+# Windows 7
+# The Microsoft C compiler provided with either:
+## Windows SDK 7.0 or greater
+## Visual Studio 2008 or greater
+
+
+==Current state of development==
+
+Initial distribution:
+* The EiffelRibbon library is not usable directly. The EiffelRibbon design tool allows you to design a ribbon and will generate code that relies on the EiffelRibbon library.
+* A class <code>EV_RIBBON_TITLED_WINDOW</code> is provided with the library. <code>EV_RIBBON_TITLED_WINDOW</code> is a descendant of the standard EiffelVision 2 class <code>EV_TITLED_WINDOW</code>. The ribbon classes generated by EiffelRibbon tool can be added only to instances of <code>EV_RIBBON_TITLED_WINDOW</code>.
+
+==Known issues and limitations==
+
+Initial distribution:
+* Resizing policy is not yet supported.
+* When working in Application Mode, it is necessary to freeze the target system each time the EiffelRibbon code is regenerated. This is not necessary in DLL Mode.
+
+