Development/Architecture/KDE3/Icon Loader/gl: Difference between revisions

From KDE TechBase
(Importing a new version from external source)
(Importing a new version from external source)
 
(44 intermediate revisions by the same user not shown)
Line 23: Line 23:


<syntaxhighlight lang="cpp-qt">
<syntaxhighlight lang="cpp-qt">
QPixmap loadIcon( QString name, int group, int size=0,
QPixmap loadIcon( QString nome, int grupo, int tamano=0,
                   int state=KIcon::DefaultState,  
                   int estado=KIcon::DefaultState,  
                   QString *path_store=0L, bool canReturnNull=false);
                   QString *ruta_almacenamento=0L, bool podeDevolverNulo=false);
</syntaxhighlight>
</syntaxhighlight>


As you see, there are a lot of parameters. The first two are most important:
Como pode observar, son moitos os parámtros que pode recibir o método. Os máis importantes son os dous primeiros:


# '''name''' - The name of the icon to load. You must pass the bare icon name here, without extension.
# '''nome'''. O nome da icona a cargar. Debe indicar o nome a secas, sen extensión.
# '''group''' - The icon group. This is explained below.
# '''grupo'''. O grupo ao que pertence a icona. O concepto de grupo explícase máis adiante.


=== Icon groups  ===
=== Grupos de iconas ===


The idea of an ''icon group'' is an important concept in the KDE icon
O concepto de «grupo de icona» ten grande importancia dentro do esquema de iconas de KDE. O grupo denota en que parte da pantalla vai empregarse a icona. Esta información é relevante porque os usuarios de KDe poden asociar resolucións de iconas e efectos visuais a cada grupo. Ao pasarlle o grupo ao cargador de iconas, está a indicar que versión da icona cargar. E que o parámetro sexa obrigatorio axuda a conseguir unha aparencia consistente e personalizábel no conxunto do ambiente de escritorio KDE.
scheme. The icon group denotes where on the screen the icon is going to be used.  
This is relevant because the KDE user can bind icon sizes and visual effects to
each group. When passing the icon group to the icon loader, you are in fact telling
it which incarnation of the icon to load. And by requiring the group argument, the
iconloader provides the means to have a consistent and configurable icon look over
the whole KDE desktop.


For example: The user can configure that he wants 32 pixel icons with 0.2
Por exemplo, un usuario pode escoller iconos de 32×32 píxeles cunha desaturación de 0,2 para as barras de ferramentas principais.
desaturation for the main toolbars.


The available icon groups are given below. All are defined in the
A continuación lístanse os grupos dispoñíbeis. Todos eles están definidos na clase [http://api.kde.org/3.5-api/kdelibs-apidocs/kdecore/html/classKIcon.html KIcon], polo que deben ir prefixados con ''KIcon::'' (por exemplo, <code>KIcon::Desktop</code>).
[http://api.kde.org/3.5-api/kdelibs-apidocs/kdecore/html/classKIcon.html KIcon]
class, so prefix them with ''KIcon::''.


* '''Desktop''' - Icons for use on the desktop, in the filemanager and similar places.
* '''Desktop'''. Iconas para empregar no escritorio, no xestor de ficheiros e en espazos similares.
* '''Toolbar''' - Icon for in normal toolbars.
* '''Toolbar'''. Iconas para barras de ferramentas estándar.
* '''MainToolbar''' - Icons for in the main toolbar. An application can have multiple toolbars, of which one is allways the main toolbar. This typically has entries like "Save" and "Open" and contains larger icons than the other toolbars.
* '''MainToolbar'''. Iconas para a barra de ferramentas principal. Un mesmo aplicativo pode ter varias barras de ferramentas; sempre haberá uha delas que sexa a principal. Adoita ser a que contén entradas como «Gardar» e «Abrir», e ten iconas máis grandes que o resto de barras.
* '''Small''' - Various small icons, like the ones in popup menus, listviews and treelists.
* '''Small'''. Varias iconas pequenas, como as que aparecen nos menús contextuais, listas e árbores.
* '''User''' - Special group for loading application specific icons. This is explained in section 3: Installing icons.
* '''User'''. Grupo especial para cargar iconas específicas de cada aplicativo. Véxase [[#Instalar iconas|Instalar iconas]].


So, to load the icon "kfind" for use in the ''Desktop'' group, you'd use:
Por tanto, para cargar a icona «kfind» para o seu uso no grupo «Desktop», deberá empregar o seguinte código:


<syntaxhighlight lang="cpp-qt">
<syntaxhighlight lang="cpp-qt">
QPixmap icon;
QPixmap icona;
icon = loader->loadIcon("kfind", KIcon::Desktop);
icona = cargador->loadIcon("kfind", KIcon::Desktop);
</syntaxhighlight>
</syntaxhighlight>


=== loadIcon continued  ===
=== Información adicional sobre loadIcon() ===


Now lets discuss the other parameters of ''loadIcon''.
Vexamos agora o resto dos parámetros que se lle poden pasar a <code>loadIcon()</code>.


# '''size''' - Override the globally configured size for the specified icon group. Effects bound to the group are still applied.
# '''tamano'''. Resolución a empregar para a icona, ignorando o valor co que está configurado o grupo. Os efectos asociados ao grupo aplicaranse de todos xeitos.
# '''state''' - The icon state. The icon state is one of ''KIcon::DefaultState'', ''KIcon::ActiveState'' or ''KIcon::DisabledState''. The icon state denotes in which state the icon is. Toolbar buttons, for example, are in state ''active'' if the mouse pointer is above them, in state ''disabled'' when they are not available, and ''default'' otherwise. Each icon state can have different effects assigned to it to give the user visual feedback.
# '''estado'''. O estado da icona. Os valor pode ser calquera dos seguintes: <code>KIcon::DefaultState</code> (''normal''), <code>KIcon::ActiveState</code> (''activo'') e <code>KIcon::DisabledState</code> (''desactivado''). Os botóns das barras de ferramentas, por exemplo, vólvense ''activos'' cando o cursor está situado sobre eles, están ''desactivados'' cando as súas accións non están dispoñíbeis, e o seu estado é ''normal'' no resto das situacións. Cada estado pode levar asociados distintos efectos para fornecer información ao usuario de maneira visual.
# '''path_store''' - If you want to know where the icon you just loaded is in the filesystem, you can pass a pointer to a QString here and the icon path is stored there.
# '''ruta_almacenamento'''. Se quere saber a ruta na que está almacenada a icona que cargou, forneza neste parámetro un punteiro a QString; a ruta gardarase na cadea apuntada.
# '''canReturnNull''' - If the requested icon is not found, the result of ''loadIcon'' depends on this parameter. If ''canReturnNull'' is ''true'', a null pixmap will be returned, if not, the "unknown" icon is returned.
# '''podeDevolverNulo'''. En caso de non atopar a icona indicada, o valor a devolver dependerá deste parámetro. Se o parámetro leva o valor <code>true</code>, devolverase un mapa de píxeles nulo; en caso contrario, devolverase a icona «unknown» (''descoñecido'').


== Installing icons ==
== Instalar iconas ==


Icons may come in different sizes and display depths.
As iconas poden estar dispoñíbeis en distintas resolucións e profundidades de cor. Neste caso, falamos de «iconas de tema visual», mentres que en caso contrario falaremos de «iconas independentes».
I shall refer to these icons as ''themed icons''. Icons that come in
just one form are referred to as ''unthemed icons''.


=== Default icon sizes ===
=== Resolucións predeterminadas de iconas ===


Themed icons come in different sizes and display depths. The standard sizes
As iconas de tema visual están dispoñíbeis en distintas resolucións e profundidades de cor. Os tamaños estándar son:
are:


;40 Colors
;40 cores
:16x16 pixels
:16×16 píxeles.
:22x22 pixels
:22×22 píxeles.
:32x32 pixels
:32×32 píxeles.


;Truecolor
;Cor real
:22x22 pixels
:22×22 píxeles.
:32x32 pixels
:32×32 píxeles.
:48x48 pixels
:48×48 píxeles.


Please refer to the [http://www.kde-artists.org/introduction.html KDE icon factory]
Visite a [http://www.kde-artists.org/introduction.html fábrica de iconas de KDE] para informarse, entre outras cousas, de que resolucións son obrigatorias. Lembre que todas estas resolucións poden asociarse a un grupo de iconas.
for information on which icon sizes are mandatory and more.
Remember that each of these sizes can be bound to an icon group.


=== Icon context ===
=== Contexto das iconas ===


Themed icons are stored in a directory hierarchy according to their
As iconas de tema visual almacénanse nunha xerarquía de directorios segundo (1) a súa '''profundidade de cor''', (2) '''resolución''', e (3) '''contexto'''. O concepto de «contexto» é unha novidade introducida polo esquema de iconas de KDE. O contexto dunha icona é o que ''representa'' a icona. Estes son os contextos estándar:
'''1. depth''', '''2. size''' and '''3. context'''.
The term ''context'' is new concept introduced by the KDE icon scheme.  
The context of an icon is what the icon ''means''. The standard
contexts are given below:


* '''action''' - The icon represents an action in a toolbar, for example "Open" or "Save".
* '''action'''. A icona representa unha acción nunha barra de ferramentas. Por exemplo, «Abrir» ou «Gardar».
* '''application''' - The icon represents an application, for example "kfind".
* '''application'''. A icona representa un aplicativo. For exemplo, «kfind» representa KFind.
* '''device''' - The icon represents something related to a device, for example "floppy" or "mount".
* '''device'''. A icona representa algo relacionado cun dispositivo. Por exemplo, «floppy» (''disquete'') our «mount» (''montar'').
* '''filesystem''' - The icon represents something in the filesystem, for example "directory", "socket" or "trashcan".
* '''filesystem'''. A icona representa un elemento do sistema de ficheiros. Por exemplo, «directory» (''directorio''), «socket» (''sócket'') ou «trashcan» (''lixo'').
* '''mimetype''' - The icon represents an mimetype, for example "text/html".
* '''mimetype'''. A icona representa un tipo de ficheiro MIME. Por exemplo, «text/html».


''Contexts'' are important in one case: selecting an
Os ''contextos'' son importantes á hora de escoller a icona. Cando o usuario vai escoller unha icona, en vez de amosarlle a lista completa de iconas do sistema, o usuario pode filtrar a lista de iconas escollendo un contexto.
icon. When an application wants the user to select an icon for, say, a  
toolbar, it would be very user unfriendly to show every single icon
installed in KDE.  Instead, it is much better to let the user select
an icon from the "action" icons only. These all represent some action and
therefore are suitable for in toolbars.


=== Directory hierarchy  ===
=== Xerarquía de directorios ===


The directory hierarchy in which themed icons are stored follows.
A seguinte é a xerarquía de directorios nos que se almacenan as iconas de tema visual.
The directory names are self explanatory.


  hicolor/
  hicolor/
Line 143: Line 119:
         ...
         ...


=== Directory roots ===
=== Directorio raíz ===


Themed icons can be installed either globally with respect to KDE, or in
As iconas de tema visual poden instalarse de maneira global, con respecto á instalación de KDE, ou nun lugar específico para cada aplicativo. No caso da instalación global, a xerarquía do tema de iconas parte do directorio {{path|$KDEDIR/share/icons}}; no caso da instalación por aplicativo, a xerarquía partirá de {{path|$KDEDIR/share/apps/$APPNAME/icons}}.
application specific place. In the global case, the icon theme hierarchy
resides under {{path|$KDEDIR/share/icons}} while in the application specific
case, it is under {{path|$KDEDIR/share/apps/$APPNAME/icons}}.


=== Installing themed icons ===
=== Instalar iconas de tema visual ===


The KDE source configuration system (specifically, am_edit) has support for
O sistema de configuración das fontes de KDE —e en concreto <code>am_edit</code>— permite a instalación de iconas de tema visual. O primeiro que debe facer é nomear as iconas de xeito que quede claro onde quedarán instaladas, tal e como se indica na seguinte táboa:
installing themed icons. First, you have to name your icons in a way that it
is clear where it must be installed. The naming convention is explained in
the table below:


{|
{|
!|depth
!|profundidade de cor
! size
! resolución
! -
! -
! context
! contexto
! -
! -
! name
! nome
! .png
! .png
|-
|-
|| hi || 16 || || action
|| hi || 16 || || action  
|-
|-
|| lo || 22 || || app
|| lo || 22 || || app
|-
|-
||    || 32 || || device
||    || 32 || || device  
|-
|-
||    || 48 || || filesys
||    || 48 || || filesys
Line 177: Line 147:
|}
|}


Examples:
Exemplos:


  lo22-action-open.png
  lo22-action-open.png
  hi48-app-kfind.png
  hi48-app-kfind.png


To install these icons globally, add this line to your <tt>Makefile.am</tt>.
Para instalar estas iconas de maneira global, engada a seguinte liña ao ficheiro {{path|Makefile.am}}.


  KDE_ICON = open kfind
  KDE_ICON = open kfind


and to install them in an application specific directory, use this:
Para instalala nun directorio específico do aplicativo, empregue estas:


  icondir = $(kde_datadir)/myapp/icons
  icondir = $(kde_datadir)/myapp/icons
  icon_ICON = open kfind
  icon_ICON = open kfind


=== Loading themed icons ===
=== Cargar iconas de tema visual ===
Themed icons are loaded with the iconloader, using the standard icon groups.
As iconas de tema visual cárganse co cargador de iconas, empregando os grupos de iconas estándar. Por exemplo:
For example:


<syntaxhighlight lang="cpp-qt">
<syntaxhighlight lang="cpp-qt">
QPixmap pm;
QPixmap icona;
pm = loader->loadIcon("kfind", KIcon::Desktop);
icona = cargador->loadIcon("kfind", KIcon::Desktop);
</syntaxhighlight>
</syntaxhighlight>


This will load the "kfind" icon, of depth and size specified for the
Isto cargará a icona «kfind», coa profundidade de cor e resolución coas que está configurado o grupo ''Desktop''.
''Desktop'' group.


=== Unthemed icons ===
=== Iconas independentes ===


Unthemed icons are installed in {{path|$KDEDIR/share/apps/$APPNAME/pics}}.
As iconas independentes instálanse en {{path|$KDEDIR/share/apps/$APPNAME/pics}}. Para instalalas, engada o seguinte ao seu ficheiro {{path|Makefile.am}}.
To install them, use this in you <tt>Makefile.am</tt>.


  icondir = $(kde_datadir)/myapp/pics
  icondir = $(kde_datadir)/myapp/pics
  icon_DATA = open kfind
  icon_DATA = open kfind


You must not give the icons special names.
Non ten que nomear as iconas de ningún xeito especial, e ademais as iconas non se procesarán, é dicir, nin se lles aplicarán efectos nin se terán en conta a súa profundidade de cor e resolución.
Also, no further processing is done on them: no effects and size,depth selection
is done.


Unthemed icons can be loaded with the iconloader using the ''User''
As iconas independentes poden cargarse co cargador de iconas, indicando o grupo ''User'':
group. This will load a user icon:


<syntaxhighlight lang="cpp-qt">
<syntaxhighlight lang="cpp-qt">
QPixmap pm;
QPixmap icona;
pm = loader->loadIcon("myicon", KIcon::User);
icona = cargador->loadIcon("unhaicona", KIcon::User);
</syntaxhighlight>
</syntaxhighlight>


== Conclusion ==
== Conclusión ==
There are 3 ways to install icons: global themed, application
Existen tres xeitos de instalar iconas: de maneira global como parte dun tema visual, como parte do tema visual dun aplicativo en concreto, ou de maneira independente. Escolla a instalación que mellor se adapte ás súas necesidades.
specific themed and unthemed. All types of icons can be loaded with the
iconloader. You should choose a specific installation depending on your
needs.




''Initial Author:'' Geert Jansen [mailto:[email protected] &lt;[email protected]&gt;]
''Autor inicial:'' Geert Jansen [mailto:[email protected] &lt;[email protected]&gt;]


[[Category:KDE3]]
[[Category:KDE3/gl]]
[[Category:Architecture]]
[[Category:Arquitectura/gl]]

Latest revision as of 09:43, 22 December 2012


Cargar e instalar iconas en KDE

As iconas son un elemento importante da interface de usuario de calquera ambiente de escritorio. Ben por escolla do usuario, ben polas propias limitacións do hardware, unha mesma icona pode fornecerse en diferentes resolucións e profundidades de cor. Para xestionar a situación dunha maneira fácil, desenvolveuse un xeito estándar de almacenar e acceder ás iconas.

Cargar iconas

Acceder ao cargador de iconas

As iconas cárganse mediante a clase KIconLoader. Todo aplicativo de KDe conta cun obxecto de carga de iconas global. Pode acceder ao obxecto co seguinte código:

#include <kglobal.h>
#include <kiconloader.h>

KIconLoader *cargador = KGlobal::iconLoader();

Cargar iconas con loadIcon()

O cargador de iconas non se limita só a iso; tamén garda as iconas na caché e aplícalles efectos. Para cargar unha icona, empregue o método loadIcon(); a súa declaración é a seguinte:

QPixmap loadIcon( QString nome, int grupo, int tamano=0,
                  int estado=KIcon::DefaultState, 
                  QString *ruta_almacenamento=0L, bool podeDevolverNulo=false);

Como pode observar, son moitos os parámtros que pode recibir o método. Os máis importantes son os dous primeiros:

  1. nome. O nome da icona a cargar. Debe indicar o nome a secas, sen extensión.
  2. grupo. O grupo ao que pertence a icona. O concepto de grupo explícase máis adiante.

Grupos de iconas

O concepto de «grupo de icona» ten grande importancia dentro do esquema de iconas de KDE. O grupo denota en que parte da pantalla vai empregarse a icona. Esta información é relevante porque os usuarios de KDe poden asociar resolucións de iconas e efectos visuais a cada grupo. Ao pasarlle o grupo ao cargador de iconas, está a indicar que versión da icona cargar. E que o parámetro sexa obrigatorio axuda a conseguir unha aparencia consistente e personalizábel no conxunto do ambiente de escritorio KDE.

Por exemplo, un usuario pode escoller iconos de 32×32 píxeles cunha desaturación de 0,2 para as barras de ferramentas principais.

A continuación lístanse os grupos dispoñíbeis. Todos eles están definidos na clase KIcon, polo que deben ir prefixados con KIcon:: (por exemplo, KIcon::Desktop).

  • Desktop. Iconas para empregar no escritorio, no xestor de ficheiros e en espazos similares.
  • Toolbar. Iconas para barras de ferramentas estándar.
  • MainToolbar. Iconas para a barra de ferramentas principal. Un mesmo aplicativo pode ter varias barras de ferramentas; sempre haberá uha delas que sexa a principal. Adoita ser a que contén entradas como «Gardar» e «Abrir», e ten iconas máis grandes que o resto de barras.
  • Small. Varias iconas pequenas, como as que aparecen nos menús contextuais, listas e árbores.
  • User. Grupo especial para cargar iconas específicas de cada aplicativo. Véxase Instalar iconas.

Por tanto, para cargar a icona «kfind» para o seu uso no grupo «Desktop», deberá empregar o seguinte código:

QPixmap icona;
icona = cargador->loadIcon("kfind", KIcon::Desktop);

Información adicional sobre loadIcon()

Vexamos agora o resto dos parámetros que se lle poden pasar a loadIcon().

  1. tamano. Resolución a empregar para a icona, ignorando o valor co que está configurado o grupo. Os efectos asociados ao grupo aplicaranse de todos xeitos.
  2. estado. O estado da icona. Os valor pode ser calquera dos seguintes: KIcon::DefaultState (normal), KIcon::ActiveState (activo) e KIcon::DisabledState (desactivado). Os botóns das barras de ferramentas, por exemplo, vólvense activos cando o cursor está situado sobre eles, están desactivados cando as súas accións non están dispoñíbeis, e o seu estado é normal no resto das situacións. Cada estado pode levar asociados distintos efectos para fornecer información ao usuario de maneira visual.
  3. ruta_almacenamento. Se quere saber a ruta na que está almacenada a icona que cargou, forneza neste parámetro un punteiro a QString; a ruta gardarase na cadea apuntada.
  4. podeDevolverNulo. En caso de non atopar a icona indicada, o valor a devolver dependerá deste parámetro. Se o parámetro leva o valor true, devolverase un mapa de píxeles nulo; en caso contrario, devolverase a icona «unknown» (descoñecido).

Instalar iconas

As iconas poden estar dispoñíbeis en distintas resolucións e profundidades de cor. Neste caso, falamos de «iconas de tema visual», mentres que en caso contrario falaremos de «iconas independentes».

Resolucións predeterminadas de iconas

As iconas de tema visual están dispoñíbeis en distintas resolucións e profundidades de cor. Os tamaños estándar son:

40 cores
16×16 píxeles.
22×22 píxeles.
32×32 píxeles.
Cor real
22×22 píxeles.
32×32 píxeles.
48×48 píxeles.

Visite a fábrica de iconas de KDE para informarse, entre outras cousas, de que resolucións son obrigatorias. Lembre que todas estas resolucións poden asociarse a un grupo de iconas.

Contexto das iconas

As iconas de tema visual almacénanse nunha xerarquía de directorios segundo (1) a súa profundidade de cor, (2) resolución, e (3) contexto. O concepto de «contexto» é unha novidade introducida polo esquema de iconas de KDE. O contexto dunha icona é o que representa a icona. Estes son os contextos estándar:

  • action. A icona representa unha acción nunha barra de ferramentas. Por exemplo, «Abrir» ou «Gardar».
  • application. A icona representa un aplicativo. For exemplo, «kfind» representa KFind.
  • device. A icona representa algo relacionado cun dispositivo. Por exemplo, «floppy» (disquete) our «mount» (montar).
  • filesystem. A icona representa un elemento do sistema de ficheiros. Por exemplo, «directory» (directorio), «socket» (sócket) ou «trashcan» (lixo).
  • mimetype. A icona representa un tipo de ficheiro MIME. Por exemplo, «text/html».

Os contextos son importantes á hora de escoller a icona. Cando o usuario vai escoller unha icona, en vez de amosarlle a lista completa de iconas do sistema, o usuario pode filtrar a lista de iconas escollendo un contexto.

Xerarquía de directorios

A seguinte é a xerarquía de directorios nos que se almacenan as iconas de tema visual.

hicolor/
    22x22/
        actions/
        apps/
        devices/
        filesystems/
        mimetypes/
    32x32/
        ...
    48x48/
        ...

locolor/
    16x16/
        ...
    22x22/
        ...
    32x32/
        ...

Directorio raíz

As iconas de tema visual poden instalarse de maneira global, con respecto á instalación de KDE, ou nun lugar específico para cada aplicativo. No caso da instalación global, a xerarquía do tema de iconas parte do directorio $KDEDIR/share/icons; no caso da instalación por aplicativo, a xerarquía partirá de $KDEDIR/share/apps/$APPNAME/icons.

Instalar iconas de tema visual

O sistema de configuración das fontes de KDE —e en concreto am_edit— permite a instalación de iconas de tema visual. O primeiro que debe facer é nomear as iconas de xeito que quede claro onde quedarán instaladas, tal e como se indica na seguinte táboa:

profundidade de cor resolución - contexto - nome .png
hi 16 action
lo 22 app
32 device
48 filesys
mime

Exemplos:

lo22-action-open.png
hi48-app-kfind.png

Para instalar estas iconas de maneira global, engada a seguinte liña ao ficheiro Makefile.am.

KDE_ICON = open kfind

Para instalala nun directorio específico do aplicativo, empregue estas:

icondir = $(kde_datadir)/myapp/icons
icon_ICON = open kfind

Cargar iconas de tema visual

As iconas de tema visual cárganse co cargador de iconas, empregando os grupos de iconas estándar. Por exemplo:

QPixmap icona;
icona = cargador->loadIcon("kfind", KIcon::Desktop);

Isto cargará a icona «kfind», coa profundidade de cor e resolución coas que está configurado o grupo Desktop.

Iconas independentes

As iconas independentes instálanse en $KDEDIR/share/apps/$APPNAME/pics. Para instalalas, engada o seguinte ao seu ficheiro Makefile.am.

icondir = $(kde_datadir)/myapp/pics
icon_DATA = open kfind

Non ten que nomear as iconas de ningún xeito especial, e ademais as iconas non se procesarán, é dicir, nin se lles aplicarán efectos nin se terán en conta a súa profundidade de cor e resolución.

As iconas independentes poden cargarse co cargador de iconas, indicando o grupo User:

QPixmap icona;
icona = cargador->loadIcon("unhaicona", KIcon::User);

Conclusión

Existen tres xeitos de instalar iconas: de maneira global como parte dun tema visual, como parte do tema visual dun aplicativo en concreto, ou de maneira independente. Escolla a instalación que mellor se adapte ás súas necesidades.


Autor inicial: Geert Jansen <[email protected]>