Development/Tutorials/Using KActions (es): Difference between revisions

From KDE TechBase
No edit summary
(translation to spanish)
Line 15: Line 15:


==Resumen==
==Resumen==
This tutorial introduces the concept of actions. Actions are a unified way of supplying the user with ways to interact with your program.
Este tutorial introduce el concepto de las aciones. Las acciones son una forma unificada de proporcionar al usuario la forma de interactuar con tu programa.


For example, if we wanted to let the user of [[Development/Tutorials/Using_KXmlGuiWindow|Tutorial 2 ]] clear the text box by clicking a button in the toolbar, from an option in the File menu or through a keyboard shortcut, it could all be done with one {{class|KAction}}.
Por ejemplo, si queremos permitir que el usuario del [[Development/Tutorials/Using_KXmlGuiWindow_(es)|Tutorial 2]] pueda borrar la caja de texto pulsando un botón de la barra de herramientas, desde una entrada del menú File o a través de un atajo de teclado, podemos realizarlo con un {{class|KAction}}.


[[image:introtokdetutorial3.png|frame|center]]
[[image:introtokdetutorial3.png|frame|center]]


==KAction==
==KAction==
A {{class|KAction}} is an object which contains all the information about the icon and shortcuts that is associated with a certain action. The action is then connected to a [http://doc.trolltech.com/latest/signalsandslots.html slot] which carries out the work of your action.
Un {{class|KAction}} es un objeto que contiene toda la información sobre el icono y el atajo de teclado asociado a una determinada acción. La acción se conecta a un [http://doc.trolltech.com/latest/signalsandslots.html slot], que lleva a cabo el trabajo de la acción.


== El código ==
== El código ==
Line 49: Line 49:
}
}
</code>
</code>
This time, very little has changed in <tt>main.cpp</tt>, only the KAboutData constructor has been updated to show that we are now on tutorial 3.
Esta vez pocas cosas han cambiado en <tt>main.cpp</tt>, solo se ha actualizado la declaración de KAboutData para indicar que ahora estamos en el tutorial 3.


===mainwindow.h===
===mainwindow.h===
Line 71: Line 71:
#endif
#endif
</code>
</code>
Only a function <tt>void setupActions()</tt> has been added which will do all the work setting up the KActions.
Sólo se ha añadido la función <tt>void setupActions()</tt>, que realizará el trabajo de configurar los KActions.


===mainwindow.cpp===
===mainwindow.cpp===
Line 110: Line 110:


==Explicación==
==Explicación==
This builds upon the KXmlGuiWindow code from [[Development/Tutorials/Using_KXmlGuiWindow|Tutorial 2]]. Most of the changes are to <tt>mainwindow.cpp</tt>, an important structural change being that the constructor for MainWindow now calls <tt>setupActions()</tt> instead of <tt>setupGUI()</tt>. <tt>setupActions()</tt> is where the new KAction code goes before finally calling <tt>setupGUI()</tt> itself.
El archivo está basado en el codigo de KXmlGuiWindow del [[Development/Tutorials/Using_KXmlGuiWindow_(es)|Tutorial 2]]. La mayoría de los cambios están en <tt>mainwindow.cpp</tt>, un cambio estructural importante es que el constructor de MainWindow ahora llama a <tt>setupActions()</tt> en vez de a <tt>setupGUI()</tt>. En <tt>setupActions()</tt> va el nuevo código de KAction antes de llamar a <tt>setupGUI()</tt>.


===Creando el objeto KAction===
===Creando el objeto KAction===
The KAction is built up in a number of steps. The first is including the <tt>KAction</tt> library and then creating the KAction:
KAction se construye en varios pasos. El primero es incluir la biblioteca <tt>KAction</tt> y crear el KAction:
<code cppqt>
<code cppqt>
#include <KAction>
#include <KAction>
Line 119: Line 119:
KAction* clearAction = new KAction(this);
KAction* clearAction = new KAction(this);
</code>
</code>
This creates a new KAction called <tt>clearAction</tt>.
Crear un KAction nuevo llamado <tt>clearAction</tt>.


===Estableciendo las propiedades de KAction===
===Estableciendo las propiedades de KAction===
====Texto====
====Texto====
Now we have our KAction object, we can start setting its properties. The following code sets the text that will be displayed in the menu and under the <tt>KAction</tt>'s icon in the toolbar.
Ahora que tenemos nuestro objeto KAction, podemos empezar a establecer sus propiedades. El siguiente código establece el texto que se mostrará en el menú y el de debajo del icono del <tt>KAction</tt> en la barra de herramientas:
<code cppqt>clearAction->setText(i18n("Clear"));</code>
<code cppqt>clearAction->setText(i18n("Clear"));</code>
Note that the text is passed through the i18n() function; this is necessary for the UI to be translatable (more information on this can be found in the [[Development/Tutorials/Localization/i18n|i18n tutorial]]).
Ten en cuenta que el texto se pasa a través de la función i18n(), esto es necesario para para que la UI pueda ser traducida (puedes encontrar mas información en el [[Development/Tutorials/Localization/i18n|tutorial de i18n]]).


====Icono====
====Icono====
If the action is going to be displayed in a toolbar, it's nice to have an icon depicting the action. The following code sets the icon to the standard KDE <tt>document-new</tt> icon through the use of the <tt>setIcon()</tt> function:
Si la acción va a mostrarse en el la barra de herramientas, estaría bien que tuviera un icono que la representara. El siguiente código establece como icono el icono estandar de KDE <tt>document-new</tt> mediante el uso de la función <tt>setIcon()</tt>:
<code cppqt>clearAction->setIcon(KIcon("document-new"));</code>
<code cppqt>clearAction->setIcon(KIcon("document-new"));</code>


====Atajo de teclado====
====Atajo de teclado====
Setting a keyboard shortcut to perform our action is equally simple:
Establecer un atajo de teclado para lanzar nuestra acción es igual de simple:
<code cppqt>clearAction->setShortcut(Qt::CTRL + Qt::Key_W);</code>
<code cppqt>clearAction->setShortcut(Qt::CTRL + Qt::Key_W);</code>
This associates Ctrl+W with the KAction.
Asocia Ctrl+W a la acción.


===Añadir a la colección===
===Añadir a la colección===
In order for the action to be accessed by the XMLGUI framework (explained in depth later) it must be added to the application's ''action collection''. The action collection is accessed via the <tt>actionCollection()</tt> function like this:  
Para que la acción sea accesible por el framework XMLGUI (explicado en profundidad mas adelante) debe añadirse a la ''colección de acciones'' de la aplicación. La colección de acciones es accesible mediante la función <tt>actionCollection()</tt>:  
<code cppqt>
<code cppqt>
actionCollection()->addAction("clear", clearAction);
actionCollection()->addAction("clear", clearAction);
</code>
</code>
Here, the <tt>clearAction</tt> KAction is added to the collection and given a name of ''clear''. This name (''clear'') is used by the XMLGUI framework to refer to the action.
Con esta llamada, la KAction <tt>clearAction</tt> se añade a la colección y toma el nombre de ''clear''. Este nombre (''clear'') lo usa el framework XMLGUI para referirse a la acción.


====Conectando la acción====
====Conectando la acción====
Now that the action is fully set up, it needs to be connected to something useful. In this case (because we want to clear the text area), we connect our action to the <tt>clear()</tt> action belonging to a KTextEdit (which, unsurprisingly, clears the KTextEdit)
Ahora que hemos establecido la acción, es necesario conectarla a algo útil. En este caso (porque queremos limpiar el área de texto), conectamos nuestra acción con la acción <tt>clear()</tt> perteneciente a KTextEdit (que como era de esperar, limpia KTextEdit):
<code cppqt>
<code cppqt>
connect( clearAction, SIGNAL( triggered(bool) ),  
connect( clearAction, SIGNAL( triggered(bool) ),  
         textArea, SLOT( clear() ) );
         textArea, SLOT( clear() ) );
</code>
</code>
This is the same as it would be done in Qt with a {{qt|QAction}}.
Es lo mismo que se llevaría a cabo en Qt con una {{qt|QAction}}.


===KStandardAction===
===KStandardAction===
Para las acciónes que normalmente aparecen en casi todas las aplicaciones KDE, como 'quit', 'save', y 'load', existen unas acciones ya creadas, accesibles a través de [http://api.kde.org/4.0-api/kdelibs-apidocs/kdeui/html/namespaceKStandardAction.html KStandardAction].


For actions which would likely appear in almost every KDE application such as 'quit', 'save', and 'load' there are pre-created convenience KActions, accessed through [http://api.kde.org/4.0-api/kdelibs-apidocs/kdeui/html/namespaceKStandardAction.html KStandardAction].
Son muy sencillas de usar. Una vez que has incluido las bibliotecas (<tt>#include <KStandardAction></tt>), simplemente añadelas con la función que quieras que realicen. Por ejemplo:
 
They are very simple to use. Once the library has been included (<tt>#include <KStandardAction></tt>), simply supply it with what you want the function to do and which KActionCollection to add it to. For example:
<code cppqt>KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</code>
<code cppqt>KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</code>
This creates a KAction with the correct icon, text and shortcut and even adds it to the File menu.
Crea una KAction con el icono correcto, el texto y el atajo de teclado, e incluso la añade al menú File.


==Añadir la acción a los menús y a las barras de herramientas==
==Añadir la acción a los menús y a las barras de herramientas==
At the moment, the new "Clear" action has been created but it hasn't been associated with any menus or toolbars. This is done with a KDE technology called XMLGUI, which does nice things like movable toolbars for you.
Por el momento, hemos creado la nueva acción "Clear" pero no se ha asociado a ningun menú o barra de herramientas. Esto lo podemos hacer con una tecnologia de KDE llamada XMLGUI, que hace cosas majas como barras de herramientas móviles.


{{note|In a later version of KDE4, XMLGUI, may be replaced with a new framework called liveui. For now, XMLGUI, is the only and correct way to set up the UI.}}
{{note_(es)|En una versión posterior de KDE4, XMLGUI puede ser reemplazada por un nuevo framework llamado liveui. Por ahora, XMLGUI es la única manera correcta de configurar la UI.}}


==XMLGUI==
==XMLGUI==
La función <tt>setupGUI()</tt> de la clase {{class|KXmlGuiWindow}} depende del sistema XMLGUI para construir la GUI, el cual la realiza analizando el archivo de descripción XML de la interfaz.


The <tt>setupGUI()</tt> function in {{class|KXmlGuiWindow}} depends on the XMLGUI system to construct the GUI, which XMLGUI does by parsing an XML file description of the interface.
La regla para establecer el nombre del archivo XML es <tt>appnameui.rc</tt>, donde <tt>appname</tt> es el nombre que estableces en {{class|KAboutData}} (en este caso, ''tutorial 3''). Por lo que en nuestro ejemplo, llamamos al archivo <tt>tutorial3ui.rc</tt>, y está localizado en el directorio del código. Cmake maneja donde será puesto el archivo en última instancia.  
 
The rule for naming this XML file is <tt>appnameui.rc</tt>, where <tt>appname</tt> is the name you set in {{class|KAboutData}} (in this case, ''tutorial3''). So in our example, the file is called <tt>tutorial3ui.rc</tt>, and is located in the build directory. Where the file will ultimately be placed is handled by CMake.


==Archivo ''appname''ui.rc==
==Archivo ''appname''ui.rc==
 
Como la descripción de la UI está definida en el archivo XML, el layout debe seguir unas reglas estrictas. Este tutorial no profundizará en exceso en este aspecto, pero para mas información puedes echar un vistazo a la [[Development/Architecture/KDE4/XMLGUI_Technology|página de XMLGUI]] (aqui tienes un tutorial antiguo: [http://developer.kde.org/documentation/tutorials/xmlui/preface.html])
Since the description of the UI is defined with XML, the layout must follow strict rules. This tutorial will not go into great depth on this topic, but for more information, see the [[Development/Architecture/KDE4/XMLGUI_Technology|detailed XMLGUI page]] (here is an older tutorial: [http://developer.kde.org/documentation/tutorials/xmlui/preface.html]).


===tutorial3ui.rc===
===tutorial3ui.rc===
Line 191: Line 188:
</code>
</code>


The <tt><Toolbar></tt> tag allows you to describe the toolbar, which is the bar across the top of the window normally with icons. Here it is given the unique name ''mainToolBar'' and its user visible name set to ''Main Toolbar'' using the <tt><text></tt> tag. The clear action is added to the toolbar using the <tt><Action></tt> tag, the name parameter in this tag being the string that was passed to the KActionCollection with <tt>addAction()</tt> in <tt>mainwindow.cpp</tt>.
La etiqueta <tt><Toolbar></tt> permite describir la barra de herramientas, que normalmente es la barra con los iconos de la parte superior de la ventana. Se le da el nombre único de ''mainToolBar'', y usando la etiqueta <tt><text></tt>, es visible a los usuarios con el nombre ''Main Toolbar''. La accion clear se añade a la barra de herramientas usando la etiqueta <tt><Action></tt>, el nombre del parametro en esta etiqueta es la cadena que pasamos a KActionCollection con <tt>addAction()</tt> en <tt>mainwindow.cpp</tt>.


Besides having the action in the toolbar, it can also be added to the menubar. Here the action is being added to the ''File'' menu of the <tt>MenuBar</tt> the same way it was added to the toolbar.
Besides having the action in the toolbar, it can also be added to the menubar. Here the action is being added to the ''File'' menu of the <tt>MenuBar</tt> the same way it was added to the toolbar.

Revision as of 20:24, 21 September 2008


Development/Tutorials/Using_KActions


Como usar KActions y XMLGUI
Serie   Tutorial para principiantes
Requisitos previos   Tutorial 2 - KXmlGuiWindow, Conocimiento básico de XML
Siguiente   Tutorial 4 - Saving and loading
Lectura avanzada   Nada

Resumen

Este tutorial introduce el concepto de las aciones. Las acciones son una forma unificada de proporcionar al usuario la forma de interactuar con tu programa.

Por ejemplo, si queremos permitir que el usuario del Tutorial 2 pueda borrar la caja de texto pulsando un botón de la barra de herramientas, desde una entrada del menú File o a través de un atajo de teclado, podemos realizarlo con un KAction.

KAction

Un KAction es un objeto que contiene toda la información sobre el icono y el atajo de teclado asociado a una determinada acción. La acción se conecta a un slot, que lleva a cabo el trabajo de la acción.

El código

main.cpp

  1. include <KApplication>
  2. include <KAboutData>
  3. include <KCmdLineArgs>
  1. include "mainwindow.h"

int main (int argc, char *argv[]) {

 KAboutData aboutData( "tutorial3", "tutorial3",
     ki18n("Tutorial 3"), "1.0",
     ki18n("A simple text area using KAction etc."),
     KAboutData::License_GPL,
     ki18n("Copyright (c) 2007 Developer") );
 KCmdLineArgs::init( argc, argv, &aboutData );
 KApplication app;

 MainWindow* window = new MainWindow();
 window->show();
 return app.exec();

} Esta vez pocas cosas han cambiado en main.cpp, solo se ha actualizado la declaración de KAboutData para indicar que ahora estamos en el tutorial 3.

mainwindow.h

  1. ifndef MAINWINDOW_H
  2. define MAINWINDOW_H
  1. include <KXmlGuiWindow>
  2. include <KTextEdit>

class MainWindow : public KXmlGuiWindow {

 public:
   MainWindow(QWidget *parent=0);
 private:
   KTextEdit* textArea;
   void setupActions();

};

  1. endif

Sólo se ha añadido la función void setupActions(), que realizará el trabajo de configurar los KActions.

mainwindow.cpp

  1. include "mainwindow.h"
  1. include <KApplication>
  2. include <KAction>
  3. include <KLocale>
  4. include <KActionCollection>
  5. include <KStandardAction>

MainWindow::MainWindow(QWidget *parent)

   : KXmlGuiWindow(parent)

{

 textArea = new KTextEdit;
 setCentralWidget(textArea);
 setupActions();

}

void MainWindow::setupActions() {

 KAction* clearAction = new KAction(this);
 clearAction->setText(i18n("Clear"));
 clearAction->setIcon(KIcon("document-new"));
 clearAction->setShortcut(Qt::CTRL + Qt::Key_W);
 actionCollection()->addAction("clear", clearAction);
 connect(clearAction, SIGNAL(triggered(bool)),
         textArea, SLOT(clear()));
 KStandardAction::quit(kapp, SLOT(quit()),
                       actionCollection());
 setupGUI();

}

Explicación

El archivo está basado en el codigo de KXmlGuiWindow del Tutorial 2. La mayoría de los cambios están en mainwindow.cpp, un cambio estructural importante es que el constructor de MainWindow ahora llama a setupActions() en vez de a setupGUI(). En setupActions() va el nuevo código de KAction antes de llamar a setupGUI().

Creando el objeto KAction

KAction se construye en varios pasos. El primero es incluir la biblioteca KAction y crear el KAction:

  1. include <KAction>

... KAction* clearAction = new KAction(this); Crear un KAction nuevo llamado clearAction.

Estableciendo las propiedades de KAction

Texto

Ahora que tenemos nuestro objeto KAction, podemos empezar a establecer sus propiedades. El siguiente código establece el texto que se mostrará en el menú y el de debajo del icono del KAction en la barra de herramientas: clearAction->setText(i18n("Clear")); Ten en cuenta que el texto se pasa a través de la función i18n(), esto es necesario para para que la UI pueda ser traducida (puedes encontrar mas información en el tutorial de i18n).

Icono

Si la acción va a mostrarse en el la barra de herramientas, estaría bien que tuviera un icono que la representara. El siguiente código establece como icono el icono estandar de KDE document-new mediante el uso de la función setIcon(): clearAction->setIcon(KIcon("document-new"));

Atajo de teclado

Establecer un atajo de teclado para lanzar nuestra acción es igual de simple: clearAction->setShortcut(Qt::CTRL + Qt::Key_W); Asocia Ctrl+W a la acción.

Añadir a la colección

Para que la acción sea accesible por el framework XMLGUI (explicado en profundidad mas adelante) debe añadirse a la colección de acciones de la aplicación. La colección de acciones es accesible mediante la función actionCollection(): actionCollection()->addAction("clear", clearAction); Con esta llamada, la KAction clearAction se añade a la colección y toma el nombre de clear. Este nombre (clear) lo usa el framework XMLGUI para referirse a la acción.

Conectando la acción

Ahora que hemos establecido la acción, es necesario conectarla a algo útil. En este caso (porque queremos limpiar el área de texto), conectamos nuestra acción con la acción clear() perteneciente a KTextEdit (que como era de esperar, limpia KTextEdit): connect( clearAction, SIGNAL( triggered(bool) ),

        textArea, SLOT( clear() ) );

Es lo mismo que se llevaría a cabo en Qt con una QAction.

KStandardAction

Para las acciónes que normalmente aparecen en casi todas las aplicaciones KDE, como 'quit', 'save', y 'load', existen unas acciones ya creadas, accesibles a través de KStandardAction.

Son muy sencillas de usar. Una vez que has incluido las bibliotecas (#include <KStandardAction>), simplemente añadelas con la función que quieras que realicen. Por ejemplo: KStandardAction::quit(kapp, SLOT(quit()), actionCollection()); Crea una KAction con el icono correcto, el texto y el atajo de teclado, e incluso la añade al menú File.

Añadir la acción a los menús y a las barras de herramientas

Por el momento, hemos creado la nueva acción "Clear" pero no se ha asociado a ningun menú o barra de herramientas. Esto lo podemos hacer con una tecnologia de KDE llamada XMLGUI, que hace cosas majas como barras de herramientas móviles.

noframe
noframe
En una versión posterior de KDE4, XMLGUI puede ser reemplazada por un nuevo framework llamado liveui. Por ahora, XMLGUI es la única manera correcta de configurar la UI.
Nota


XMLGUI

La función setupGUI() de la clase KXmlGuiWindow depende del sistema XMLGUI para construir la GUI, el cual la realiza analizando el archivo de descripción XML de la interfaz.

La regla para establecer el nombre del archivo XML es appnameui.rc, donde appname es el nombre que estableces en KAboutData (en este caso, tutorial 3). Por lo que en nuestro ejemplo, llamamos al archivo tutorial3ui.rc, y está localizado en el directorio del código. Cmake maneja donde será puesto el archivo en última instancia.

Archivo appnameui.rc

Como la descripción de la UI está definida en el archivo XML, el layout debe seguir unas reglas estrictas. Este tutorial no profundizará en exceso en este aspecto, pero para mas información puedes echar un vistazo a la página de XMLGUI (aqui tienes un tutorial antiguo: [1])

tutorial3ui.rc

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE kpartgui SYSTEM "kpartgui.dtd"> <gui name="tutorial3" version="1">

 <ToolBar name="mainToolBar" >
   <text>Main Toolbar</text>
   <Action name="clear" />
 </ToolBar>
 <MenuBar>
   <Menu name="file" >
     <Action name="clear" />
   </Menu>
 </MenuBar>

</gui>

La etiqueta <Toolbar> permite describir la barra de herramientas, que normalmente es la barra con los iconos de la parte superior de la ventana. Se le da el nombre único de mainToolBar, y usando la etiqueta <text>, es visible a los usuarios con el nombre Main Toolbar. La accion clear se añade a la barra de herramientas usando la etiqueta <Action>, el nombre del parametro en esta etiqueta es la cadena que pasamos a KActionCollection con addAction() en mainwindow.cpp.

Besides having the action in the toolbar, it can also be added to the menubar. Here the action is being added to the File menu of the MenuBar the same way it was added to the toolbar.

Change the 'version' attribute of the <gui> tag if you changed .rc file since the last install to force a system cache update.

Some notes on the interaction between code and the .rc file: Menus appear automatically and should have a <text/> child tag unless they refer to standard menus. Actions need to be created manually and inserted into the actionCollection() using the name in the .rc file. Actions can be hidden or disabled, whereas menus can't.

CMake

Finally, the tutorial3ui.rc needs to go somewhere where KDE can find it (can't just leave it in the source directory!). This means the project needs to be installed somewhere.

CMakeLists.txt

project(tutorial3)

find_package(KDE4 REQUIRED) include_directories(${KDE4_INCLUDES})

set(tutorial3_SRCS

 main.cpp
 mainwindow.cpp

)

kde4_add_executable(tutorial3 ${tutorial3_SRCS})

target_link_libraries(tutorial3 ${KDE4_KDEUI_LIBS})

install(TARGETS tutorial3 DESTINATION ${BIN_INSTALL_DIR}) install(FILES tutorial3ui.rc

       DESTINATION  ${DATA_INSTALL_DIR}/tutorial3)

This file is almost identical to the one for tutorial2, but with two extra lines at the end that describe where the files are to be installed. Firstly, the tutorial3 target is installed to the BIN_INSTALL_DIR then the tutorial3ui.rc file that describes the layout of the user interface is installed to the application's data directory.

Make, instalar y ejecutar

If you don't have write access to where your KDE4 installation directory, you can install it to a folder in your home directory.

To tell CMake where to install the program, set the DCMAKE_INSTALL_PREFIX switch. You probably just want to install it somewhere local for testing (it's probably a bit silly to go to the effort of installing these tutorials to your KDE directory), so the following might be appropriate:

mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
make install
$HOME/bin/tutorial3

which will create a KDE-like directory structure in your user's home directory directory and will install the executable to $HOME/bin/tutorial3.

Avanzando

Now you can move on to saving and loading.