Guía de uso del Control Ribbon similar a Microsoft Office 365

Traducción libre de la documentación del Control Ribbon similar a Microsoft Office 365 de Doug Hennig.

El proyecto proporciona un Control Ribbon similar al de Microsoft Office 365 para ser usado en formularios VFP

El código fuente del proyecto y la documentación en inglés se encuentra en: https://github.com/DougHennig/Ribbon

Nota: la traducción se hizo con la documentación al día 06 de enero de 2021.

---

Usando el Control Ribbon

Para agregar un control ribbon a un formulario, suelte una instancia de la clase SFRibbon de SFRibbon.vcx en el formulario y luego escriba el código en algún método del formulario o quizás en el método Init del objeto del ribbon, para agregar pestañas, secciones y botones; consulte la sección "Componentes" para obtener más detalles.

Para implementar el control ribbon en su aplicación, agregue lo siguiente al proyecto:

• SFRibbon.vcx
• SFGDIMeasureString.prg
• SFRibbonDown.png
• SFRibbonRight.png
• RibbonThemes.xml

Además, incluya System.app con los archivos instalados de su aplicación.

Componentes

El control ribbon consta de varios componentes, todos los cuales están definidos en la biblioteca de clases visuales SFRibbon.vcx:

• Una pestaña (la clase SFRibbonTab) es un elemento del menú en la parte superior, como "Home" y "Send/Receive" de la imagen de arriba. Para agregar una pestaña al ribbon, llame al método AddTab, pasando opcionalmente el nombre de la pestaña (si no se pasa, AddTab asigna un nombre único). Establezca la propiedad "Caption" del objeto Tab devuelto por AddTab.

      loTab = Thisform.oRibbon.AddTab('Home')
      loTab.Caption = 'Home'
  

  Las pestañas tienen una propiedad "Selected" que es .T. para la pestaña seleccionada y .F. para todas las demás pestañas. Establezca esta propiedad en .T. para seleccionar una pestaña mediante programación:

      Thisform.oRibbon.Home.Selected = .T.
  

• Cada pestaña tiene una barra de herramientas (una instancia de la clase SFRibbonToolbar) debajo. No necesita preocuparse por las barras de herramientas, ya que están allí solo para su comodidad: cuando se selecciona una pestaña, su barra de herramientas se hace visible y las barras de herramientas de las otras pestañas están ocultas.

• Una sección (la clase SFRibbonToolbarSection) es un conjunto de botones con una barra separadora a la derecha y un título en la parte inferior. Puede haber varias secciones en una barra de herramientas. Para agregar una sección, llame al método AddSection de una pestaña (que en realidad agrega una sección a la barra de herramientas de una pestaña), pasando opcionalmente el nombre de la sección (si no se pasa, AddSection asigna un nombre único). Establezca la propiedad Caption del objeto de sección devuelto por AddSection

      loSection = loTab.AddSection()
      loSection.Caption = 'New'
  

• Hay dos tipos de botones: normales (la clase SFRibbonToolbarButton) y horizontales (la clase SFRibbonToolbarButtonHorizontal). La diferencia es que los botones normales están dispuestos de izquierda a derecha y tienen una imagen de 32 x 32 con un título debajo, mientras que los botones horizontales se apilan uno encima del otro y tienen una imagen de 16 x 16 con un título a la derecha. Puede haber varios botones en una sección. Al hacer clic en un botón, se ejecuta un comando o se muestra un menú desplegable (que se explica a continuación).

  Para agregar un botón normal, llame al método AddButton de una sección, pasando opcionalmente el nombre del botón (si no se pasa, AddButton asigna un nombre único).

  Para agregar un botón horizontal, llame al método AddHorizontalButton de una sección, pasando opcionalmente el nombre del botón (si no se pasa, AddHorizontalButton asigna un nombre único).

  Establezca las propiedades Caption, Image, Command y EnabledExpression del objeto  botón devuelto por AddButton o AddHorizontalButton. Para utilizar un título de varias líneas, incluya un retorno de carro (carácter CHR(13)) en el texto del título. El código en Command se ejecuta a través de la función EXECSCRIPT(), por lo que puede constar de varias declaraciones separadas por retornos de carro si es necesario. EnabledExpression contiene opcionalmente una expresión (como una cadena) que el método Refresh evalúa para determinar si el botón está habilitado.

        loButton = loSection.AddButton()
        with loButton
            .Caption = 'New' + chr(13) + 'Email'
            .Image   = 'newmail.png'
            .Command = 'Thisform.NewMail()' + chr(13) + 'Thisform.Refresh()'
            .EnabledExpression = 'Thisform.IsButtonEnabled()'
        endwith
        loButton = .AddHorizontalButton()
        with loButton
            .Caption = 'Ignore'
            .Image   = 'ignore.png'
            .Command = 'Thisform.Ignore()'
        endwith
  

• Un botón puede tener un menú desplegable; si es así, aparece una pequeña flecha hacia abajo en el título del botón. El botón tiene un menú si tiene barras. Para agregar una barra al menú, llame al método AddBar del botón, pasando el título de la barra (use "\<" delante del carácter utilizado como tecla de acceso rápido para la barra tal como lo haría con un menú de VFP) , el comando a ejecutar, opcionalmente una imagen para la barra (16 x 16), y opcionalmente una expresión que determina cuando la barra está habilitada (si no se pasa, la barra siempre está habilitada).

  Para agregar una barra separadora, no pase ningún parámetro al método AddBar.

  Para agregar un submenú a una barra de menú, llame al método AddBar del objeto de barra devuelto por AddBar. Por ejemplo, en el código siguiente, el botón "New Items" tiene un menú con cuatro barras: "E-mail Message", "Appointment", un separador y "E-mail Message Using", el último de los cuales tiene un submenú con "More Stationery...", un separador, y barras de "Plain Text", "Rich Text" y "HTML".

        loButton = .AddButton('NewItems')
        with loButton
            .Caption = 'New' + chr(13) + 'Items'
            .Image   = 'newitems.png'
            .AddBar('E-\<mail Message', 'Thisform.Email()', 'newemailsmall.png')
            .AddBar('\<Appointment', 'Thisform.Appointment()', 'appointmentsmall.png')
            .AddBar()
            loBar = .AddBar('E-mail Message \<Using')
            loBar.AddBar('\<More Stationery...', 'Thisform.MoreStationery()')
            loBar.AddBar()
            loBar.AddBar('\<Plain Text')
            loBar.AddBar('\<Rich Text')
            loBar.AddBar('\<HTML')
        endwith
  

• El control ribbon también puede tener un menú desplegable, que se muestra al hacer clic con el botón derecho en la parte del ribbon que no está cubierta con botones. Para agregar barras al menú del ribbon, llame al método AddBar del ribbon utilizando los mismos parámetros descritos anteriormente. Los submenús también se admiten de la misma manera que se discutió anteriormente.

        Thisform.oRibbon.AddBar('Change Theme to Colorful', ;
            "Thisform.oRibbon.Theme = 'Colorful'" + chr(13) + ;
            "Thisform.Refresh()", , ;
            "Thisform.oRibbon.Theme <> 'Colorful'")
        Thisform.oRibbon.AddBar('Change Theme to Dark Grey', ;
            "Thisform.oRibbon.Theme = 'Dark Grey'" + chr(13) + ;
            "Thisform.Refresh()", , ;
            "Thisform.oRibbon.Theme <> 'Dark Grey'")
  

• Puede agregar otros tipos de controles además de botones a una sección: llame a AddControl, pasando el nombre (opcional), la clase y la biblioteca para el control. Asegúrese de llamar al método CalculateWidth para la sección, para que el ancho de la sección se ajuste en consecuencia. Por ejemplo, este código agrega un cuadro de texto:

        loControl = loSection.AddControl('Test', 'textbox', '')
        with loControl
          .FontName = 'Segoe UI'
          .Width    = 200
  		.Height   = 24
  		.Top      = int((loSection.Height - .Height)/2) && center it vertically
  	endwith
  	.CalculateWidth()
  

• Puede hacer referencia a objetos jerárquicamente por el nombre, comenzando desde el ribbon. Por ejemplo, Thisform.oRibbon.Home.Toolbar.New.NewEmail, puede hacer referencia al botón NewEmail en la sección "New" de la barra de herramientas de la pestaña Home" en el ribbon. Esta es la razón principal para pasar un nombre a los distintos métodos Add*; de lo contrario, tiene que usar los nombres asignados automáticamente al objeto, algo como Thisform.oRibbon.Tab1.Toolbar.Section1.Button1.

Comportamiento

El control ribbon tiene el siguiente comportamiento:

• La pestaña actualmente seleccionada tiene una barra debajo (una barra azul en la primera captura de pantalla anterior; el color se especifica usando el color "tabbordercolor" en el tema actual; consulte la sección "Temas" a continuación) y su título está en negrita.
• Al pasar el mouse sobre una pestaña, se resalta la pestaña en el color "tabhighlightcolor" especificado por el tema actual y, si es la pestaña seleccionada, se alarga la barra debajo de la pestaña.
• Hacer clic en una pestaña la convierte en la seleccionada y muestra la barra de herramientas para esa pestaña.
• Al pasar el mouse sobre un botón, se resalta el botón en el color "buttonhighlightcolor" especificado por el tema actual.
• Al hacer clic en un botón se ejecuta el comando para ese botón. Si no se especificó ningún comando y no hay un menú para el botón (consulte el siguiente punto), aparece un cuadro de mensaje con "No implementado".
• Aparece una flecha hacia abajo en el título de un botón si tiene un menú. Al hacer clic en el botón, se muestra el menú. Al hacer clic en el botón nuevamente, hacer clic fuera del menú o mover el mouse fuera del formulario, se oculta el menú.
• Al pasar el mouse sobre una barra de menú, se resalta la barra en el color "menuitemhighlightcolor" especificado por el tema actual.
• Al hacer clic en una barra se ejecuta el comando para esa barra. Si no se especificó ningún comando y no hay un submenú para la barra (ver el siguiente punto), aparece un cuadro de mensaje con "No implementado".
• Aparece una flecha hacia la derecha en el título de una barra si tiene un submenú. Los submenús se comportan como menús.

Temas

Un tema define un conjunto de colores para el control ribbon. El tema predeterminado es el tema "Colorido" (Colorful)

Aquí está el tema "Gris oscuro" (Darkgrey):

Los temas se definen en el archivo RibbonThemes.xml:

<themes>
	<theme name="Colorful" 
		ribbonbackcolor="243,242,241" 
		ribbonbordercolor="210,208,206" 
		ribbonshadowcolor1="234,234,234"
		ribbonshadowcolor2="238,238,238"
		ribbonshadowcolor3="243,243,243"
		ribbonshadowcolor4="247,247,247"
		ribbonshadowcolor5="251,251,251"
		menuitembackcolor="255,255,255"
		menuitemhighlightcolor="210,208,206"
		menuseparatorcolor="225,223,221"
		buttonhighlightcolor="200,198,196"
		tabhighlightcolor="250,249,248"
		tabbordercolor="16,110,190"
		sectionseparatorcolor="179,176,173"
	/>
	<theme name="Dark Grey" 
		ribbonbackcolor="190,187,184" 
		ribbonbordercolor="68,68,68" 
		ribbonshadowcolor1="75,75,75"
		ribbonshadowcolor2="82,82,82"
		ribbonshadowcolor3="88,88,88"
		ribbonshadowcolor4="95,95,95"
		ribbonshadowcolor5="102,102,102"
		menuitembackcolor="243,242,241"
		menuitemhighlightcolor="200,198,196"
		menuseparatorcolor="210,208,206"
		buttonhighlightcolor="151,149,147"
		tabhighlightcolor="200,198,196"
		tabbordercolor="32,31,30"
		sectionseparatorcolor="121,119,117"
	/>
</themes>

Los valores numéricos son colores RGB.

Los atributos del XML son:

• ribbonbackcolor: El color de fondo del ribbon.
• ribbonbordercolor: el color de la línea del borde en la parte inferior del ribbon.
• ribbonshadowcolor1, ribbonshadowcolor2, ribbonshadowcolor3, ribbonshadowcolor4 y ribbonshadowcolor5: Hay una "sombra" debajo de la línea del borde en la parte inferior del ribbon. Esta sombra en realidad consta de cinco líneas de un píxel de altura. Estos atributos especifican los colores de esas líneas.
• menuitembackcolor: El color de fondo de una barra en un menú.
• menuitemhighlightcolor: El color de fondo de una barra cuando se mueve el mouse.
• menuseparatorcolor: el color de una barra separadora en un menú.
• buttonhighlightcolor: El color de fondo de un botón cuando el mouse está sobre él.
• tabhighlightcolor: El color de fondo de una pestaña cuando el mouse está sobre él.
• tabbordercolor: el color de la línea del borde debajo de una pestaña.
• sectionseparatorcolor: El color de la línea de separación a la derecha de una sección.

Para establecer el tema del ribbon, establezca la propiedad "Theme" con el nombre del tema deseado (actualmente solo "Colorido" y "Gris oscuro"). La propiedad "Theme" del ribbon contiene una colección de los nombres de temas disponibles. El formulario Sample.scx incluido con este proyecto utiliza un cuadro combinado con Thisform.oRibbon.Themes como RowSource y Thisform.oRibbon.Theme como ControlSource para elegir el tema del ribbon.

Clases

Todas las clases de los componentes del control ribbon están en SFRibbon.vcx.

• SFRibbonBase: la clase principal para la mayoría de los componentes del ribbon, excepto como se muestra; una subclase de Container.
• SFRibbon: la clase de ribbon.
• SFRibbonTab: la clase de Tab.
• SFRibbonToolbar: la barra de herramientas de una pestaña.
• SFRibbonToolbarSection: la clase de sección.
• SFRibbonToolbarButton: una clase de botón normal.
• SFRibbonToolbarButtonHorizontal: una clase de botón horizontal; una subclase de SFRibbonToolbarButton.
• SFRibbonMenu: una clase utilizada para definir menús; una subclase de Custom.
• SFRibbonMenuBar: la clase de la barra de menú; una subclase de SFRibbonToolbarButtonHorizontal.
• SFRibbonMenuSeparator: la clase de barra separadora de menú.
• SFRibbonMenuForm: una clase de formulario que proporciona un menú desplegable; una subclase de Form.

---