Cómo programar componentes en Gambas

Contenidos

• Introducción • Clases Exportadas

• Clases Exportadas Ocultas • Controles • La constante _Properties

• Syntaxis • Tipos de Propiedades • Listas de Constantes • Ejemplos

• Las otras Constantes Especiales • La constante _DefaultEvent • La constante _DefaultSize • La constante _DrawWith • La constante _Arrangement

• Iconos de control • Requerimientos del componente • Depuración, instalación y empaquetado del componente

• Depuración • Instalación • Empaquetado

• Conclusión

IntroducciónToda la información a continuación es para Gambas 3.

Los componentes en Gambas son librerías compartidas escritas en C, C++ o directamente en Gambas que añaden nuevas clases al intérprete de gambas.

Un componente escrito en Gambas es un proyecto normal con las siguientes particularidades:

• En la pestaña "Opciones" del diálogo de Propiedades del Proyecto, el combobox "El proyecto es un componente" está seleccionado en "Sí".

• Algunas de las clases del proyecto son exportadas. • Las clases exportadas que son controles deben declarar algunas constantes públicas que

indicarán al IDE toda la información necesaria para gestionar el control. • La pestaña "Requiere" del diálogo de Propiedades del Proyecto se completa con las

dependencias del nuevo componente.

Muchos de los componentes oficiales están escritos en gambas y los puedes usar como ejemplos. El código fuente de esos componentes está localizado en el directorio /comp/src

del archivo de código fuente de gambas.

Esta es la lista de dichos componentes:

• gb.db.form • gb.form • gb.form.dialog • gb.form.mdi • gb.info • gb.report • gb.settings • gb.web

Algunos componentes escritos en C/C++ tienen también partes escritas en gambas:

• gb.qt4 • gb.gtk • gb.desktop

El código fuente de la parte de gambas está dentro del directorio fuente de ese componente. Por ejemplo, la parte de gambas de gb.qt4 está en /gb.qt4/src.

Clases ExportadasEl propósito de un componente es proporcionar nuevas clases al intérprete de Gambas.

Las clases que queremos proveer deben ser exportadas desde nuestro proyecto, de otro modo el usuario de tu proyecto no podrá verlas o usarlas.

Para marcar una clase como exportada, sólo hay que añadir la palabra clave EXPORT al principio del código de la clase.

Si un método o una propiedad de una clase exportada devuelve un objeto de otra clase declarada en tu componente, entonces esa otra clase debería de ser exportada igualmente. De otro modo, el usuario no podrá guardar una referencia a ella, a menos que use el tipo de dato Object. Si una clase exportada hereda de otra clase declarada en tu componente, esta otra clase debería de ser exportada también. De otro modo, se producirá un error cuando el intérprete intente cargar el componente. Un buen ejemplo de un componente sencillo con clases exportadas es gb.settings y su clase Settings.

Clases Exportadas Ocultas

Si tienes que exportar algunas clases que no quieres que sean visibles al usuario, puedes ocultarlas simplemente comenzando su nombre con un guión bajo.

Por ejemplo, mira el código fuente de gb.desktop y verás muchas clases exportadas que no son visibles explícitamente.

Con esto, podemos reemplazar el concepto de "clase virtual" existente sólo en componentes escritos en

C/C++.

ControlesLos controles son clases exportadas especiales que aparecen en la caja de herramientas de controles del IDE.

Los controles son generalmente elementos gráficos que muestran algo y que sirven para interactuar con el usuario. Pero también pueden ser clases normales y no tener una parte gráfica, como el control Timer. En estos casos los llamamos controles virtuales.

Los componentes gráficos (gb.qt o gb.gtk) proveen dos clases que deberías usar como "clases padre" para crear tus propio controles:

• UserControl , para controles sencillos. • UserContainer , para crear contenedores.

UserControl y UserContainer son realmente clases hijas de la clase Container. De esta forma, puedes crear nuevos controles o nuevos contenedores mezclando controles o contenedores ya existentes.

Para un buen ejemplo de uso de UserControl, mira el código fuente del control FileView. Este control contiene un TreeView y un IconView dentro de un UserControl, mostrando uno de los dos, según el tipo de vista requerido por el usuario.

Para otro ejemplo de uso de UserContainer, mira el código fuente del control ListContainer. Este control es un contenedor que permite crear un ListBox cuyos ítems son otros controles.

Los controles tienen que declarar algunos tipos de constantes ocultas que permiten al IDE gestionar el control:

Constante Tipo Por

defecto Descripción

_IsControl Boolean FALSE Esta propiedad debe establecerse a TRUE, para que una clase exportada se convierta en un control.

_IsContainer Boolean FALSE Si un control es un contenedor, es decir, si puedes poner otros controles dentro usando el editor de formularios del IDE.

_IsMultiContainer Boolean FALSE si un control es un contenedor múltiple, como el TabStrip.

_IsVirtual Boolean FALSE Si un control es virtual, es decir, una clase normal que puedes poner en el editor de formularios, como el control Timer o la clase Printer.

_IsForm Boolean FALSE Si un control es realmente un formulario, por ejemplo el contenedor de nivel superior de todos los controles de la misma familia.

_Family String "*" La familia del control, esto es, el tipo de objeto de nivel superior donde se ha de colocar el control. Por ejemplo: "Form" para un control Form, "Report" para un control Report, and "*" para

un control que se puede colocar en cualquier lugar.

_Group String _Family El nombre de la pestaña de la caja de herramientas del IDE donde se mostrará el icono del control. Por defecto se usará el nombre de la familia, pero si no se ha establecido se usará el grupo "Special".

_Similar String "" Una lista separada por comas de grupos similares. El editor de formularios del IDE permite reemplazar un control por cualquier otro que comparta los mismos grupos de similaridad. Normalmente un grupo de similaridad es el nombre de un control.

_Properties String "" La lista de propiedades del control. Ver más abajo.

_DefaultEvent String "" El evento por defecto. Ver más abajo.

_DefaultSize String "" El tamaño por defecto del control. Ver más abajo.

_DrawWith String "" El control gráfico real empleado para dibujar el control dentro del editor de formularios. Ver más abajo.

_Arrangement Integer 0 La disposición automática del control cuando éste es un contenedor y si éste dispone la posición de sus elementos hijos automáticamente. Ver más abajo.

Sólo las constantes _IsControl y _Properties son obligatorias.

Estas constantes ocultas se heredan como cualquier otra constante. Así que no necesitas declararlas en cada control, ya que hay una relación hereditaria entre ellas.

La constante _PropertiesEsta constante es la más importante y además es obligatoria. Describe todas las propiedades que aparecerán en la hoja de propiedades del IDE para ese control, su tipo, sus valores por defecto y otra información dependiente del tipo de propiedad.

Syntaxis

Esta constante especial es una cadena con la siguiente sintaxis:

PUBLIC CONST _Properties AS String = " [ * , ] Propiedad1 , Propiedad2 , ... "

Cada propiedad tiene la siguiente sintaxis:

[-] Nombre [ { Tipo [ Argumentos ] } ] = Default

• Nombre es el nombre de la propiedad. Por supuesto, la propiedad debe ser declarada e implementada en el código del control.

• Tipo es el tipo de propiedad (N. del T.: Tipo como sinónimo de "especie", no como tipo de dato o datatype). Puede ser más exacto que el tipo de dato de la propiedad. Por ejemplo, "Color" significará que la propiedad es un entero, pero la hoja de propiedades del control en el IDE abrirá un selector de colores para definir su valor. Si no se define, el tipo de propiedad es su tipo de dato (datatype).

• Argumentos son argumentos opcionales que dependen del valor de Tipo. • Default es el valor por defecto de la propiedad. La sintaxis aquí depende del tipo de propiedad.

La primera propiedad puede ser un asterisco, de forma que el control adquiere automáticamente todas las propiedades declaradas en la constante _Properties de su clase ascendiente. En ese caso, un nombre de propiedad puede comenzar con un guión medio (-) para que no aparezca en la lista de propiedades heredada de la clase padre.

Tipos de Propiedades

Aquí están los diferentes valores de Tipo soportados hasta el momento:

Tipo Propiedad Descripción Argumentos

Color Un entero que representa un color.

El IDE mostrará un selector de color emergente para editar el valor de esta propiedad.

Font Una fuente de caracteres.

El IDE mostrará un selector de fuentes emergente para editar el valor de esta propiedad.

Font [ :Fixed ]

Usar Font:Fixed para permitir fuentes fijas solamente.

Path Una ruta a un fichero.

El IDE mostrará un selector de ficheror emergente para editar el valor de esta propiedad.

Picture Una imagen localizada en el el directorio del proyecto o un icono de stock. El IDE mostrará un selector de imágenes para editar el valor de esta propiedad.

Range Un rango de números enteros con un mínimo y un máximo.

El IDE usará un control SpinBox para editar el valor de esta propiedad.

Range:Mínimo;Máximo

El valor Default value debe coincidir con el tipo de dato de la propiedad. Para propiedades booleanas, se puede especificar "True" o "False" como valor por defecto.

Hay que ser muy prudente cuando definamos (o no) el valor Default de una propiedad.

• Si no se especifica, el valor por defecto que toma es el valor por defecto asociado con el tipo de dato de la propiedad, (FALSE para una propiedad Boolean, 0 para una numérica, etc.).

• El valor por defecto debe coincidir con la implementación de la propiedad, porque cuando una propiedad se establece a su valor por defecto en el editor de formularios del IDE, no se genera ningún código para inicializar la propiedad en tiempo de ejecución.

Listas de Constantes

Para propiedades que toman su valor de una lista de constantes predefinidas de la misma clase, puedes especificar una clase en lugar de un tipo de propiedad, con una lista opcional de constantes.

Esta es la sintaxis:

Tipo de Propiedad

Descripción Argumentos

Nombre de clase Una lista de constantes.

El IDE usará un control ComboBox para editar el valor de la propiedad, y lo llenará con las constantes especificadas.

Class . ( * | Constante1 ; Constante2 ; ... ) [ = Default ]

Si usamos un asterisco en vez de una lista de propiedades, se usarán todas las constantes de la clase especificada.

Si se especifica, el valor de Default debe ser el nombre de una de las constantes, no su valor real.If specified, the value of _Default must be the name of one of the constants. Not its real value!

Ejemplos

Por ejemplo, el valor de Control._Properties es:

X{Position},Y{Position},Width{Dimension},Height{Dimension},Visible=True,Enabled=True,Font{Font},Background{Color}=-1,Foreground{Color}=-1,Tag,Mouse{Mouse.Default;Blank;Arrow;Cross;Wait;Text;SizeAll;SizeH;SizeV;SizeN;SizeS;SizeW;SizeE;SizeNWSE;SizeNESW;SplitH;SplitV;Pointing}=Default,ToolTip,Drop,Expand,Ignore

Es heredado por todos los otros controles y contenedores.

Este es el valor de ListBox._Properties:

*,List,Mode{Select.*}=Single,Sorted

Las otras Constantes Especiales

La constante _DefaultEvent

Esta constante es una cadena que representa el evento por defecto del control. Este evento por defecto

es el que se usa cuando de hace doble clic en un control en el editor de formularios del IDE.

Por ejemplo:

PUBLIC CONST _DefaultEvent AS String = "Click"

Esta constante es opcional, pero es muy conveniente declararla.

La constante _DefaultSize

Esta constante es una cadena que representa el tamaño por defecto del control cuando se suelta encima del editor de formularios al arrastrarlo desde la caja de herramientas de controles. Es su anchura y su altura como un múltiplo de Desktop.Scale, separado por comas.

Un ejemplo:

PUBLIC CONST _DefaultSize AS String = "36,36"

Esta constante es opcional. Si no se declara, el IDE tratará de hacer lo mejor posible.

La constante _DrawWith

Esta constante es una cadena que indica al IDE el control que se va a usar para dibujarlo en el editor de formularios.

Por defecto, los controles que son miembros de gb.qt, gb.qt.ext, gb.form y gb.form.mdi se dibujan siendo instanciados con el juego de propiedades Design.

Si un control no es miembro de dichos componentes, entonces el IDE dibujará un marco con el icono del control y su nombre dentro.

Al definir esta constante, el IDE no usará un DrawingArea, sino el control que se especifique.

Por ejemplo:

PUBLIC CONST _DrawWith AS String = "TextBox"

La constante _Arrangement

Esta constante es un valor de tipo cadena que representa el estilo de disposición que usa el IDE para ordenar los controles hijos dentro de un contenedor, antes de salvarlos en el disco duro.

El valor puede ser una de las siguientes cadenas:

Constante Disposición

"H" Arrange.Horizontal

"V" Arrange.Vertical

"R" Arrange.Row

"C" Arrange.Column

"F" Usa el valor real de la propiedad Arrange.

Por ejemplo:

PUBLIC CONST _DefaultArrangement AS Integer = "V" ' Arrange.Vertical

Esa constante se usa solamente si el control es un contenedor y es opcional. Si no se define, no se fuerza su disposición.

Iconos de controlCada control debe tener un icono para mostrarse en la caja de herramientas del IDE.

Para proporcionar los iconos de los controles de tu componente, debes crear un directorio /control en la raíz de tu proyecto, y colocar un fichero PNG para cada control.

En Gambas 3, el directorio del control se debe crear dentro del directorio .hidden. Esa es la sección "Proyecto" en la vista de árbol del IDE.

El nombre del icono de un control debe ser el nombre de clase del control en minúsculas con la extensión .png.

Por ejemplo:

$ cd gb.db.form$ cd control$ lsdatabrowser.png datacombo.png datacontrol.png datasource.png datatree.png dataview.png

Requerimientos del componenteSe pueden especificar los requerimientos del componente en la pestaña "Requiere" del diálogo de propiedades del proyecto.

Observa que esta pestaña no es visible cuando un proyecto no es un componente.

En esta pestaña se listarán todas las dependencias de tu componente sobre otros componentes.

La sección "Características" tiene cuatro check-boxes, cada una con una característica proporcionada por uno o varios componentes. Esta sección se usa cuando tu componente necesita una característica específica que no depende de un un componente en especial.

Si realmente se necesita algún componente específico, se pueden seleccionar en la sección "Componentes" de esta pestaña.

Los componentes seleccionados en la pestaña "Componentes" del diálogo de propiedades del proyecto, no tienen nada que ver con los componentes especificados en la pestaña "Requiere" de las propiedades del componente.

Éstos sólo se usan para correr el proyecto del componente desde el IDE con fines de depuración.

Depuración, instalación y empaquetado del componente

Depuración

Para depurar tu componente, directamente se puede usar y correr el proyecto tal cual.

La clase de inicio del proyecto y los componentes chequeados en la pestaña "Componentes" del

diálogo de propiedades de proyecto no interfiere en absoluto con el comportamiento del componente una vez instalado y en uso por otros proyectos.

Instalación

Puedes instalar el componente en el directorio de usuario chequeando la correspondiente opción en el diálogo "Crear ejecutable"

Una vez instalado, el componente será visible en la pestaña de "Componentes" del diálogo de propiedades del proyecto, como cualquier componente instalado globalmente.

Para desinstalar el componente del tu directorio de usuario, basta con desmarcar la opción en el diálogo "Crear ejecutable" y crear el ejecutable de nuevo.

Empaquetado

El IDE puede crear paquetes binarios de tu componente, igual que haría para cualquier otro proyecto normal.

Sólo hay que definir menos opciones: un componente no tiene entrada de menú, por ejemplo.

El paquete binario instalará el componente a nivel global y se podrá usar igual que cualquier otro componente proporcionado por Gambas.

Si quieres distribuir tu componente, es muy importante nombrarlo siguiendo un esquema muy preciso, para que no haya conflictos entre paquetes.

El nombre de tu componente tiene que ser: gambas3-vendedor-nombre

• gambas3 es el prefijo para todos los componentes. • vendedor es el nombre de vendedor. Para componentes oficiales de gambas, el nombre de

vendedor es simplemente gb. • nombre es el nombre del componente.

En caso de que el asistente de empaquetado permita insertar la cadena de vendedor en el nombre del paquete, por favor evita hacerlo.

Coloca el nombre de vendedor dentro del nombre de proyecto del componente, de forma que aparezca en el nombre del componente final y sea visible para el usuario.

Por el momento, hay un fallo en el empaquetador que no tiene en cuenta la versión del proyecto del componente al generar las dependencias del paquete. En consecuencia, hay que establecer la versión de tu componente a la versión de Gambas actual!

ConclusiónHe intentado encontrar la forma más fácil de crear componentes usando el IDE. Aún no es perfecta, pero si tienes alguna pregunta o comentario, por favor usa la lista de correo.

Ten en cuenta que algunas cosas cambiarán seguramente antes de la versión final de Gambas 3.

Y por supuesto, si quieres corregir o mejorar este artículo, bienvenido seas!

Componentes adicionales de Gambas

componente Los componentes en Gambas son librerías compartidas externas escritas en C, C++ o en Gambas que agregan nuevas funciones al interprete de Gambas.

Estos son almacenados en $PREFIX/lib/gambas2, el valor del $PREFIX dependen de donde este instalado Gambas en su sistema. Por default, $PREFIX esta en /usr/local.

Información relacionada con los componentes es almacenada en $PREFIX/share/gambas2/info.

Para usar un componente en un proyecto, debe seleccionar el componente en el menú Project → Propiedades, o de lo contrario obtendrá un mensaje de error:

Cannot load name class. Unable to load clase file

Cómo programar componentes en C/C++

Introducción NOTA: Esta página está en proceso de traducción. Nos vendría bien tu ayuda para terminarla

¿Qué es un componente?

Los componentes de Gambas son librerías compartidas escritas en C o C++ que añaden funciones nuevas al intérprete de Gambas.

Estos componentes actúan de forma similar a como lo hacen los drivers Linux con el kernel del sistema:

• Los componentes y el intérprete se comunican a través de la Interfaz de Programación de Gambas.

• Deben de estar compilados dentro del paquete fuente de Gambas. • Son ejecutados en el entorno del intérprete y por tanto no pueden hacer cualquier cosa.

Un componente puede contener:

• Nuevas clases que son añadidas a otras clases de Gambas. Estas clases son declaradas al intérprete usando una estructura en C que contiene la descripción de cada símbolo, método, constante y evento.

• Ganchos (hooks) del intérprete: funciones especiales que implementan importantes operaciones del intérprete, como el manejo del bucle de eventos, lectura de los parámetros del programa...

• Una interfaz de programación que mejore la Interface de Programación de Gambas, y que otros componentes pueden usar.

Un componente debe tener un nombre. Este nombre es la palabra gb seguida por una lista de palabras, separadas por un punto, que describen el papel del componente y la relación entre éste y otros componente, si la hubiera.

Por ejemplo, gb.qt.kde es un componente que transforma una aplicación Gambas en una aplicación KDE. Este componentes está relacionado con el componente gb.qt y cargar el primero implica cargar el segundo.

La Interfaz de Programación de Gambas

La Interfaz de Programación de Gambas es un conjunto de utilidades, funciones y macros que le permiten:

• Describir el componente. • Definir los ganchos (hooks) del intérprete. • Manipular matrices (arrays), tablas hash... • Manipular los tipos de datos nativos de Gambas. • Crear arrays (matrices) y colecciones de Gambas. • Lanzar eventos • Manipular los objetos de Gambas. • Cargar un fichero desde el archivo de proyecto. • Cargar otros componentes. • ...

El uso de este interfaz de programación está altamente recomendado, porque previene que un componente pueda hacer cosas dañinas.

El Interfaz de Programación de Gambas es una estructura de C que contiene un puntero de función por cada función del interfaz.

Esta estructura se declara en el archivo main del componente y la inicializa automáticamente el intérprete al cargar el componente.

Escribir buenos componentes (Components)

¡Escribir buenos componentes es bastante difícil!. Supongamos que quiere escribir un componente SDL, es decir, un componente que le permita a un proyecto de Gambas usar toda la potencia de la librería SDL: gráficos, sonido, CD-ROM...

Se puede contentar con simplemente recubrir las funciones de la librería, sus estructuras y constantes. Es el modo fácil, incluso si el recubrimiento de funciones y estructuras de C no fuera posible en todos los casos con Gambas.

Su componente sería útil, pero no muy interesante para el programador de Gambas porque se vería obligado a programar en estilo C o C++.

En lugar de hacer esto, sería mejor que se rascara un poco el cerebro para crear un interfaz distinto entre Gambas y la librería, intentando generalizar y simplificar la interfaz original de la librería.

That is what I did with QT: it is far easier to use the QT component than programming the QT library directly. And if one day somebody writes a GTK+ component, he will be able to use the same interface because I tried to generalize the QT interface by avoiding all the QT specific stuff... Well, to be honest, I put all the useful QT specific stuff into a dedicated extended component, gb.qt.ext

Component Source Organization

The source files of a component are stored in a sub-directory of the lib directory of the source package. The path of this directory reflects the name of the component.

For example, the gb.qt.kde component sources are stored in the .src/lib/qt/kde directory.

A typical component directory contains :

• The autoconf/automake stuff, i.e. a Makefile.am file that describes how to /def/compile the component. (new topic)

• One source file and one header file for each main class implemented in the component. • One main file that implements the entry points of the component. • One component description file.

For example, here is the result of ls ./src/lib/qt/kde just before the compilation :

CApplication.cpp CDatePicker.cpp CDialog.cpp lib.gb.qt.kde.component main.h Makefile.amCApplication.h CDatePicker.h CDialog.h main.cpp Makefile Makefile.in

The component source directory structure looks something like this:

-+- lib | +---+- db | | | +----- mysql | | | +----- postgresql | +----- eval | +----- example | +----- net | +---+- qt | | | +----- editor | | | +----- ext | | | +----- kde | +----- sdl

Quick Start I think the better way is starting from the sdl componente, which is very small.

So, let's suppose you want to write the gb.xyz component. This component: * Depends on no other component. * Needs the libxyz.so library and the xyz.h include file. * Needs multi-threading.

The $ROOT variable is the directory where you uncompressed the GAMBAS source package.

1. Make a copy of the $ROOT/src/lib/sdl directory (with its contents) and name it gb.xyz .

2. Remove the sources files, but keep main.c and main.h. You will write your own main.c and main.h by modifying them.

3. Edit the $ROOT/src/lib/xyz/Makefile.am file, and fills it as needed, as explained there.

You will get something like that:

INCLUDES = -I$(top_srcdir)/src/share @XYZ_INC@EXTRA_DIST = *.component

pkglib_LTLIBRARIES = lib.gb.xyz.la

lib_gb_xyz_la_LIBADD = @XYZ_LIB@lib_gb_xyz_la_LDFLAGS = @LD_FLAGS@

lib_gb_xyz_la_SOURCES = main.h main.c myFirstClass.h myFirstClass.c mySecondClass.h mySecondClass.c ...

install-exec-local: @cp -f *.component $(DESTDIR)$(pkglibdir)

4. Rename the $ROOT/src/lib/xyz/lib.gb.sdl.component file as lib.gb.xyz.component and edit it.

Be careful, this file must be UTF8 encoded.

[Component]Key=gb.xyzName=The xyz componentAuthor=YouAlpha=1

5. Edit the $ROOT/src/lib/Makefile.am file (located one directory up) and change the first line to add a reference to the newly created sub-directory.

SUBDIRS = debug eval db compress @QT_DIR@ @NET_DIR@ @SDL_DIR@ @VB_DIR@ @XYZ_DIR@

6. Edit the $ROOT/configure.in file and add the following stuff:

...

GB_COMPONENT( xyz, XYZ, [XYZ component], [GB_FIND(xyz.h, /usr/local /usr, include xyz*/include include/xyz*)], [GB_FIND(libxyz.$SHLIBEXT, /usr/local /usr, lib xyz*/lib lib/xyz*)], [$C_LIB $THREAD_LIB -lxyz], [$THREAD_INC])

...

7. At the end of the $ROOT/configure.in file, change the AC_OUTPUT macro:

...

dnl ---- Create makefiles

AC_OUTPUT( Makefile src/Makefile src/share/Makefile src/comp/Makefile src/exec/Makefile src/lib/Makefile ...src/lib/compress/Makefile src/lib/compress/zlib/Makefile src/lib/compress/bzlib2/Makefile src/lib/xyz/Makefile )

8. Open a terminal, go to the package root directory, and type:

$ ./reconf$ ./configure...$ make...

Everything should compile... if you didn't make a mistake of course :-)

9. To test the component, you must make three symbolic links from the ./src/lib/xyz directory to the Gambas installation directory. As root, of course:

$ su...# ln -s /usr/lib/gambas/lib.gb.xyz.component $ROOT/src/lib/xyz/lib.gb.xyz.component# ln -s /usr/lib/gambas/lib.gb.xyz.so $ROOT/src/lib/xyz/.libs/lib.gb.xyz.so# ln -s /usr/lib/gambas/lib.gb.xyz.la $ROOT/src/lib/xyz/lib.gb.xyz.la

10. Now you must create the component description files by using the gbi command. You must do that each time you modify the interface of your component.

$ gbi -a...

That's all. You should have a new component now :-)

The main file

The interpreter hooks

Writing classes

Special methods

The components description file

Diferencias con Visual Basic

Mientras Gambas no intenta ser un clon de Microsoft Visual Basic, utiliza BASIC y hay varias similitudes entre los dos lenguajes, y algunas relaciones en las características.

Posiblemente hay más similitudes que diferencias, pero no puedes copiar un proyecto de VB e intentar compilarlo bajo Gambas.

El símbolo aparecerá algunas veces en las páginas de esta documentación, para indicar que hay

notas disponibles que enseñan a usar la característica descrita en esa página y que difiere de la forma de ejecutar la misma tarea en VB. La intención es ayudar a aquellos programadores que esten migrando a Gambas desde ese lenguaje.

Diferencias no referentes al lenguaje• En VB el código de cada formulario y el objeto formulario están incluidos en el mismo archivo.

Gambas usa dos archivos separados para ello: archivo .form y un archivo .clase .

• Extensiones de los archivos:

Tipo de Archivo Visual Basic

Gambas

Archivo de definición del proyecto

.vbp .project (uno por directorio)

Módulo .bas .module

Archivo de Class .cls .class

Archivo de definición del Form .frm .form

Archivos de recursos binarios .frx Algún otro archivo almacenado en el directorio del

proyecto.

• Los proyectos de Gambas se definen con un directorio que tiene un archivo .project dentro, y todos los arhivos en ese directorio. VB permite tener múltiples archivos de proyecto en distintos directorios, o usar el mismo archivo fuente de un directorio en distintos proyectos, lo que tiene sus ventajas y sus inconvenientes.

• Las medidas de la pantalla se hacen en VB en "twips", que son un 1/1440 de pulgada; en Gambas se hacen en píxeles reales.

• Los controles de los Form son privados por defecto en los programas de Gambas. Se puede cambiar este comportamiento en las Propiedades del Proyecto, marcando el recuadro "Los controles del formulario son públicos".

• Las funciones de conversión Str$, Val, CStr... se comportan de forma distinta. Por ejemplo, Str$ y Val usan la configuración de idioma puesta en Gambas, mientras que no hacen eso en Visual Basic. Lea la documentación atentamente para más detalle, pero parece que el comportamiento de Gambas es más lógico :-).

Lo que VB tiene y Gambas no• No se puede editar el código en modo de depuración en Gambas; es necesario detener la

ejecución del programa.

• En Gambas, los tipos de datos simples (Integer, String, etc.) se pasan por valor a los procedimientos y funciones. No se pueden pasar por referencia como en Visual Basic. Recuerde que VB pasa los parámetros por referencia si no se usa la palabra clave ByVal, así que tenga cuidado cuando intente portar un proyecto VB. También se pasan siempre por referencia el contenido de los tipos de datos objeto (array , collections, objects) en ambos lenguajes.

Pasar argumentos por referencia, ahora es posible en la versión en desarrollo.

• No existe nada parecido a una variable global para todo el proyecto en Gambas. Para simularlo se puede hacer una clase llamada Global y declarar las variables globals como variables públicas estáticas de esa clase, entonces se puede referir a ellas como Global.nombre_de_la_variable en todo el proyecto. No es una práctica de programación muy elegante, pero al menos funcionará como una variable global cuando quiera usarla ;)

• En un módulo de VB, a no ser que incluya la frase Option Explicit, no necesita declarar las variables antes de usarlas. Gambas se comporta como si Option Explicit estuviera siempre activo, lo que mejora mucho el código a expensas de trabajar un poquito más.

• No hay nada en Gambas equivalente a la propiedad Index de los controles en los formularios de VB. Es muy fácil crear arrays de controles, pero hay que hacerlo mediante código. No hay en la actualidad ninguna forma de hacerlo gráficamente. Por tanto, cuando copie y pegue un control, en lugar de preguntar si desea hacer un array de controles, lo que hace Gambas automáticamente es renombrar el control copiado con un nombre adecuado.

• No se pueden crear labels transparentes en Gambas; el fondo es siempre opaco.

Ahora es posible hacerlo en la versión en desarrollo.

• El evento MouseMove solo ocurre en Gambas cuando hay pulsado un botón del ratón. La única

excepción es el control DrawingArea, que tiene una propiedad Tracking para poder seguir los eventos del ratón incluso si no se ha pulsado ningún botón.

• En VB se pueden unir dos strings con el símbolo + . Como en Gambas el signo + sólo se usa para la suma matemática, deberá usar & cuando quiera unir dos string.

• El simbolo de dos puntos : no sirve para separar el código. Debe ponerlo en una nueva linea para esto.

• En VB 3.0 el comando Print no añadía un retorno de carro. Si solía usar para imprimir texto la instrucción printer.print, el texto se perdía. La instrucción Print en Gambas pone todo en una línea. No se pierde nada.

• En VB se puede usar Mid$() como una instrucción para quitar una subcadena y poner otra dentro de una cadena. En Gambas, no puede usarlo para asignarle u na subcadena al resultado. Por ejemplo, en VB: MiString = "El perro salta": Mid$(MiString, 5, 3) = "zorro" devuelve en MiString = "El zorro salta". Eso no funciona en Gambas. Tendrá que hacer cosas como: MiString = Left$(MiString, 4) & "zorro" & Mid$(MiString, 8).

Esta syntax de la función Mid$(), ahora es posible en la versión en desarrollo.

• Algunos de los caracteres que se pueden usar en el código de VB como identificadores, tales como el subrayado ("_"), no se aceptan en Gambas.

• Afortunadamente, en Gambas no puede ¡usar GOTO para capturar errores! En su lugar use CATCH, FINALLY o TRY .

• ENUM no puede ser usado para enumerar constantes de tipo Integer. En su lugar, usted tiene que definir cada elemento ENUM como una constante.

Example

CONST SUMA AS Integer = 1 CONST RESTA AS Integer = 2

Lo que Gambastiene y VB no• Al contrario que con VB, no necesita compilar el soporte gráfico si quiere escribir una

aplicación de consola en Gambas. Tan solo debe quitar la selección al componente gb.qt en las Propiedades del Proyecto y asegurarse de que ha definido un Sub Main().

• En lugar de la palabra clave WITH EVENTS, Usted debe establecer un "nombre de evento" a los objetos que provocan eventos. Vea la documentación de NEW para más información.

• Gambas tiene el concepto de grupos de controles, lo que permite manejar eventos de cualquier número de controles distintos dentro de una única subrutina. Esto reduce código redundante y puede usarse para hacer la mayoría de las cosas que los index de los controles de VB hacen, y algunas cosas que VB no puede hacer.

• Mientras que VB es imposible ejecutar un programa de forma síncrona y recibir su salida sin aprender a hacer llamadas a la API de windows (Shell simplermente lanza el programa, sin esperar nada) Gambas permite hacerlo usando SHELL y EXEC, controlar el proceso que inicia

usando la clase Process, e incluso leer y escribir en el proceso, lo que facilita añadir funcionalidades a aplicaciones y asistentes. Esto hace que sea muy fácil escribir interfaces gráficas con Gambas para casi cualquier programa de consola

• Se puede hacer todo lo anterior con los dispositivos de Unix y archivos especiales también, como puertos serie o paralelo. Use el sistema de archivos /proc para escribir un monitor RAID, por ejemplo, o use una tubería para obtener múltiples canales de información desde el back-end de un programa hecho en cualquier otro lenguaje.

• Para hacer una ventana con formas extrañas, solo hay que asignar la ME.Picture y la propiedad ME.Mask de la ventana usando una imagen que tenga áreas transparentes. VB necesita para eso llamadas a la API y algo más de trabajo.

• Se pueden crear controles y menús de forma dinámica, tan sólo necesita instanciarlos con la instrucción NEW.

• Se puede insertar un formulario de Gambas dentro de otro: cuando instancie el primero, especifique el segundo como parent.

• Los controles tienen los eventos Enter y Leave, lo que le permite saber cuando el puntero del ratón entra en un control y cuando lo abandona. Se pueden usar para implementar fácilmente efectos mouse-over.

• Se pueden leer datos de archivos binarios y manejar automáticamente la forma de colocar sus bytes (endianness), usando la propiedad ByteOrder de la clase Stream.

• Gambas usa internamente el juego de caracteres UTF-8, por lo que se puede internacionalizar fácilmente todo el proyecto.

• Gambas es Software libre y su entorno de desarrollo está escrito en Gambas, lo que le permite un grado máximo de personalización, sólo dependiendo de su nivel de conocimientos de BASIC.

Y muchas otras cosas... ¡Añádelas aquí siempre que quieras! :-)

Same Functionality, Different Terminology• End Sub/End Function: see END.

• Exit Sub/Exit Function: see RETURN. Also, rather than setting a variable with the same name as the function and then exiting the function, you can simply include the desired return value as a parameter to RETURN.

• End (end program): see QUIT.

• Arrays use brackets instead braces. So use DIM x[9] AS Float instead DIM x(9) AS Float

• Arrays do not have the extra element for indexing as 1..n, index must always be 0..(n-1)

• On Error Goto: see TRY, CATCH and FINALLY.

• Msgbox: see Message. Normally you'd want Message.Info.

• VB's default InputBox function (pop up a ../../comp/gb.form/dialog prompting for a value which is returned to the calling program) has no direct equivalent in Gambas yet, but see the

InputBox page for a clase you can download and include in your projects to serve the same purpose (and more.)

• DoEvents: see WAIT. WAIT also replaces the frequently used Windows API "sleep" function.

• Inserting Double Quotes in Strings: Rather than two consecutive double quotes as in VB, use the backslash as an escape character as in C or Perl (").

• VScrollBar, HScrollBar: Gambas' ScrollBar replaces both of these. It automatically figures out whether you want a vertical or horizontal scrollbar based on the control's dimensions: make it wide, and you get a horizontal scrollbar; make it tall, and get a vertical one.

• Open and Save dialogs: You can use either the Qt or enhanced KDE dialogs in place of the Windows common dialog. Some of the properties are named differently and filters are specified with a String array, like this: [ "Filter 1 (*.foo)" , "Filter 2 (*.bar)" ]

• Validating text entry: In VB, certain events have a Cancel parameter you can set to prevent the evento from being handled normally after your handler is done, so that for instance you can allow only letters or numbers to be typed, perform field validation, or force entry to be all upper or lower case. In Gambas, this is done by using the STOP EVENT instruction.

• Keyboard and Mouse event handlers does not take parameters. They use instead static public members of the Mouse and Key classes. For example:

• Mouse .X and Mouse.Y for the mouse coordinates. • Mouse .Left to know if the left button is pressed. • Key .Code to get the code of a key. • Key .Shift to know if the SHIFT key is pressed. • ...and so on.

• In Gambas, the Timer() routine returns the number of elapsed seconds since the program start. In VB, it returns the number of elapsed seconds since midnight.

• Do not use the Form.Load método. It is a completely different method from the Visual Basic Load instruction. In Gambas, it is just a static method that creates the implicit form instance.

Preguntas Frecuentes

¿Por que este proyecto se llama "Gambas"?Parece que todos los proyectos de Software libre, tienen nombre de animales, especialmente los lenguajes de programación como: Python, Camel, Bonobo, etc.

Y yo buscaba un acronimo recursivo con la palabra "Basic" en ella. Así que Gambas Almost Means BASic! (Gambas Casi Significa Basic).

¿Gambas es compatible con Visual Basic™?¡No, y nunca lo sera!. Afortunadament, hay muchas similitudes, pero no esperes tomar tu codigo viejo de Visual Basic y correrlo en Gambas sin ningún cambio. Tu puedes localizar y resolver muchos problemas relacionados con las diferencias entre los dos lenguajes leyendo la siguiente página: Diferencias con Visual Basic.

¿Gambas sera compatible con Java or .Net?Nunca, me temo. Hay muchas razones, buenas y malas: Yo no soy Sun o Microsoft, yo no quiero imponer un solo lenguaje para todo en todas partes. Una cosa estupida, ¿o no lo es? :-) Yo quiero un simple y poderoso lenguaje, no necesariamente para profesionales o nerds. Yo hago esto por diversión también!. Me gusta escribir compiladores, interpretes, máquinas virtual... Entonces yo no use el spec de Java o .Net. El IDE de Gambas esta escrito en Gambas.

¿Gambas es Multiplataforma?En un futuro, yo espero que la respuesta sera un simple: "¡Si!". :) Pero ahora, hay reportes de personas compilando Gambas bajo BSD y Win32/Cygwin.

¿Por que no mezclar el proyecto con HBasic, MonoBasic, Parrot...?Existen muchas diferencias técnicas entre esos proyectos y el mio como para pensar en mezclarlos.

Otro problema es que el interprete de Gambas esta limitado a las necesidades del lenguaje que yo necesito. .Net/Parrot tienen necesidades muy diferentes a las de Gambas. No solo es cuestión de interpretar el bytecode. Por ejemplo, esta el problema del conteo de referencia sobre el recolector de basura. ¿Que le pasara al administrador de los componentes del sistema? ¿Al administrador de clases inherentes? Y también a...

¿Como puedo compilar e instalar Gambas?Por favor leea el LÉEME

¿Como puedo desinstalar Gambas?Si instalaste Gambas usando el sistema de paquetes de tu sistema operativo, entonces es fácil, solo utiliza la forma habitual de desinstalar paquetes. _

Si tu instalaste el codigo fuente como root, entonces solo borra el directorio donde esta instalado. Por ejemplo, si tu instalaste Gambas bajo /opt/gambas2, como root teclea:

$ rm -rf /opt/gambas2

Si el prefijo de la instalación es /usr o /usr/local (Que es la configuración por defecto) entonces tu tienes que borrar cada directorio uno por uno.

$ rm -f /usr/local/bin/gbx2 /usr/local/bin/gbc2 /usr/local/bin/gba2 /usr/local/bin/gbi2$ rm -rf /usr/local/lib/gambas2$ rm -rf /usr/local/share/gambas2

¿Puedo acceder a las bases de datos como PostgreSQL, MySQL, etc. en GambasActualmente puedes acceder a las bases de datos de PostgreSQL, MySQL y SQLite en la versión estable, y algunas otras en la versión en desarrollo. Si tu quieres desarrollar un driver para otro sistema de base de datos, dímelo. Serás bienvenido!

Yo soy un programador de C/C++. ¿Puedo Ayudar?Por supuesto, tu ayuda es bienvenida! Primero, puedes suscribirte a la lista de correo para desarrolladores y presentarte tu mismo. Entonces, puedes intentar entender la arquitectura de Gambas, el compilador, el interprete, el ambiente de desarrollo, los componentes, y como todo este interactua entre si. Entonces, puedes leer la documentación en el Wiki: donde explica como puedes programar tu propio componente. Puedes tambien encontrar en los ejemplos un ejemplo completo de un componente llamado componente.example, leyendo el codigo fuente de este componente, puedes entender como escribir tu propio componente. Si deseas escribir un driver para la base de datos, el driver de PostgreSQL esta comentado, entonces es más fácil entender que es lo que hace. Por supuesto, yo te ayudare con cualquier pregunta que puedas tener, solo espero que tú desees invertir más que solo un año de escuela para aprender C/C++ :-)

Si no soy programador de C/C++. Como puedo ayudar?Ayuda en las siguientes tareas es muy bienvenida. Y no necesitas programar en C/C++ para hacerlas!.

• Jugar con Gambas y reportar cualquier bug. • Hacer ejemplos de programación para principiantes, y mandarmelos para que yo los incluya en

la distribución. • Hacer un tutorial para mostrar a los principiantes como escribir su primer programa en Gambas.

Esta es una gran idea! :-) • Traducir Gambas en tu propio idioma, si es que aun no se ha hecho. Por favor consulte How To

Translate The Gambas IDE para mas información. • Ayudar a traducir este Wiki al español, para ello debe Registrarse.

¿Puedo desarrollar un software comercial con Gambas?Si, tu puedes hacerlo. Pero si usas el componente de QT, por ejemplo si tu programa tiene una interfaz grafica usando QT, entonces tu tendrás que comprar la licencia de QT antes de empezar ese desarrollo. De lo contrario, tu software tendrá que ser software libre :-)

¿Portaras Gambas a Windows™ ?Yo no, pero ayudare a otras personas a intentarlo. Yo anteriormente he compilado el código fuente de Gambas en Cywin, pero eso realmente no funciono. Note que existen muchas cosas por portar, administrador de procesos, componente de Qt, y otras cosas... Es un trabajo enorme.

Como Traducir un Proyecto de Gambas Para traducir un proyecto en tu lengua nativa, abre el IDE, y haz click en traducir... en el menu Proyecto

Si el IDE muestra algun mensaje emergente, asegúrate de que tienes las herramientas GNU gettext instalado en su ordenador.

A continuación, seleccione su idioma de traducción en la lista de la izquierda.

Si la traducción no está presente en la lista de la izquierda, haga clic en el * botón * Nuevo y elegir una nueva traducción.

Si necesita traducir a un lenguaje que no existe en el directorio nueva traducción ../../comp/gb.form/dialog, escribe y lo añadiremos

Seleccione una cadena de texto sin traducir en la tabla

A continuación, introduzca su traducción en el campo de texto en la parte inferior del ../../comp/gb.form/dialog.

Puede indicar que una cadena no debe ser traducido mediante la introducción del signo menos como cadena a traducir

Repita este proceso hasta que cada cadena se traduce. Cuando haya terminado, haga clic en el Cerrar/botón.

Puedes traducir el proyecto en varias oportunidades

Puede ayuadrse con los iconos de la barra de herramientas.

De izquierda a derecha, los iconos te permiten:

• Borrar la cadena actual. • Marca una cadena como no traducibles. • Copia la cadena sin traducir al traductor. • Verificar la traduccion actual, duarnte la verificación de cada caractér sae conserva. • Buscar la siguiente cadena sin traducir. • Encuentre la cadena anterior sin traducir. • Búsqueda de un texto dentro de las cadenas a traducir, o las cadenas traducidas.

Hay otras funciones que ofrece el cuadro de diálogo de botones:

De izquierda a derecha, los botones te permiten:

• Insertar una nueva traducción a la lista de lenguas de la izquierda. • Recargar la actual traducción. Todos los cambios se pierden. • Eliminar la actual traducción. • Importación y fusionar un fichero de traducción en la actual. • Exportar la traducción actual en un archivo.

La traducción se guarda automáticamente al cambiar el lenguaje común o cuando cierra el cuadro de diálogo de traducción.

El resultado de su traducción se almacena en un *.po archivo almacenado en el directorio .lang del proyecto. El nombre de este archivo depende del idioma. Por ejemplo, la traducción al francés se llama fr.po.

Cada vez que haga una nueva versión de su proyecto, las cadenas no traducidas puede cambiar. Pero no se preocupe, sus cadenas traducidas se conservan.

• Si una cadena sin traducir desaparece, desaparece la traducción de la misma. • Si una nueva cadena sin traducir, se añade, se vuelve un vacío de traducción. • Todas las demás cadenas traducidas mantienen su traducción.}

AND

Resultado = Expression AND Expression

Dependiendo de la expresion, el operador AND puede ser un "Y logico" o un "Y numerico".

En el caso de dos expresiones booleanas, un Y logico es llevado a cabo. En el caso de dos números enteros, es un Y numerico el que se realiza.

El operador lógico Y tiene dos expresiones booleanas y devuelve un valor verdadero o falso. Los resultados devueltos por este operador se muestra en el cuadro siguiente:

A B A AND B

FALSE FALSO FALSO

FALSO TRUE FALSO

VERDADERO FALSO FALSO

VERDADERO VERDADERO VERDADERO

El operador Y numerico toma dos valores enteros y devuelve un valor entero. El cual corresponde a cada bit especificado en la siguiente tabla:

A B A AND B

0 0 0

0 1 0

1 0 0

1 1 1

El operador Y numérico se puede utilizar para probar el patrón de bits de un número. También puede utilizarse para enmascarar, un número de bits. La siguiente tabla ofrece algunos ejemplos de cómo funciona el operador AND en dos números.

Expression Explanation

10 AND 20 = 0 10 = binary 01010 20 = binary 10100 Hence 10 AND 20 = 0

10 AND -20 = 8 10 = binary 00000000000000000000000000001010 -20 = binary 11111111111111111111111111101100 Hence 10 AND -20 = 8 (binary 1000)

20 AND -20 = 4 20 = binary 00000000000000000000000000010100 -20 = binary 11111111111111111111111111101100 Hence 20 AND -20 = 4 (binary 100)

Example

PRINT TRUE AND FALSE

FalsePRINT TRUE AND TRUE

True

PRINT 7, Bin(7, 16)PRINT 11, Bin(11, 16)PRINT 7 AND 11, Bin(7 AND 11, 16)

7 000000000000011111 00000000000010113 0000000000000011

DIM A,B AS BOOLEANA = 10 < 20B = 20 > 30

IF A AND B THENPRINT "Both A and B are TRUE"ELSEPRINT "Either A or B or both are FALSE"

ENDIF

Either A or B or both are FALSE

Véase también

Operadores Aritméticos, Operadores Lógicos

Ang

Ángulo = Ang ( X AS Float , Y AS Float )

Esta función calcula el arcotangente de dos variables X e Y. Es similar a calcular el arcotangente de X / Y, salvo que el signo de ambos argumentos se emplea para determinar el cuadrante del resultado.

Esta función devuelve el resultado en radianes, con valores entre -π y π (inclusive).

Es la misma función que ATan2.

Para convertir coordenadas cartesianas en coordenadas polares, use Mag para obtener la distancia y esta función para obtener el ángulo.

Example

PRINT Deg(Ang(-1, 1))

135Funciones Trigonométricas

ACos Calcula el arcocoseno de un número.

ACosh Calcula el arcocoseno hiperbólico de un número.

Ang Calcula la coordenada "ángulo polar" para dos coordenadas cartesianas.

ASin Calcula el el arcoseno de un número.

ASinh Calcula el arcoseno hiperbólico de un número.

ATan Calcula la arcotangente de un número.

ATan2 Calcula la arcotangente de dos números.

ATanh Calcula la arcotangente hiperbólica de un número.

Cos Calcula el coseno de un ángulo.

Cosh Calcula el coseno hiperbólico de un ángulo.

Deg Convierte radianes a grados.

Hyp Calcula la hipotenusa de un triángulo.

Mag Calcula la coordenada "distancia polar" para dos coordenadas cartesianas.

Pi Devuelve π o un múltiplo de π.

Sin Calcula el seno de un ángulo.

Sinh Calcula el seno hiperbólico de un ángulo.

Tan Calcula la tangente de un ángulo.

Tanh Calcula la tangente hiperbólica de un ángulo.

Rad Convierte grados en radianes.

ACos

Valor = ACos ( Número AS Float )Valor = Acs ( Número AS Float )

Devuelve el arcocoseno de un número.

Example

PRINT ACos(0.5)

1.047197551197PRINT ACos(-1)

3.14159265359

Access

Accessible = Access ( Ruta [ , Modo ] )

Devuelve TRUE si el archivo especificado por Ruta es accesible.

El valor de Modo puede ser:

• gb .Read, devuelve TRUE si hay permiso de lectura. Es el valor por defecto. • gb .Write devuelve TRUE si hay permiso de escritura. • gb .Exec, devuelve TRUE si hay permiso de ejecución.

Los flags anteriores pueden combinarse con el operador OR.

En el caso de un directorio, el permiso de ejecución significa que hay permiso para leer el contenido de la carpeta.

Example

PRINT Access("/home/benoit", gb.Write OR gb.Exec)

TruePRINT Access("/root", gb.Write)

False

COPY

COPY Ruta Origen TO Ruta Destino

Copia un archivo desde Ruta Origen a Ruta Destino.

La ruta de destino ha de ser diferente de la ruta de origen.

Tenga en cuenta que esta función no copia carpetas de forma recursiva.

Example

' Guarda el archivo de configuración de GambasCOPY User.Home &/ ".config/gambas/gambas.conf" TO "/mnt/save/gambas.conf.save"

Errores

Mensaje Descripción

El archivo ya existe ( El archivo de destino ya existe.

Esta función emplea internamente las funciones OPEN, READ[../../def/stream] _\Stream_, WRITE y CLOSE. Por tanto, puede disparar cualquiera de sus errores.

OPEN

Flujo = OPEN Archivo por abrir FOR [ READ | INPUT ] [ WRITE | OUTPUT ] [ CREATE | APPEND ] [ WATCH ]

Abre archivos como flujos para leer, Escribir, crear o añadir datos. Debe especificarse aunque sea una un comando despues del FOR por ejemplo:

• Si se especifica CREATE, Entonces crea un archivo o lo reemplaza por uno nuevo si existe.

• Si se especifica APPEND, entonces el puntero es movido al final del archivo después de que este se abra.

• Si se especifica READ o WRITE keyword are specified, entonces la entrada-salida se escribe

directamente al archivo, no se mete en buffer.

• Si se especifica INPUT or OUTPUT, entonces la entrada-salida son almacenadas en un buffer.

• Si se especifica WATCH, el archivo se ve sin el interprete : • Si al menos un bite se puede leer del archivo, entonces se llama a event handler File_Read().

• Si al menos un bite se puede leer del archivo, Entonces se llama a evento handler File_Write() .

Si al abrir termina correctamente, el Flujo objeto retorna variable Stream.

Predeterminadamente, los streams son almacenados en buffer. Si usted quiere que no sea almacenado el Flujo, debe usar los comandos READ o WRITE.

A diferencia de otros lenguajes Basic, Gambas nunca borra el archivo, cuando es abierto por WRITE . Por eso si el archivo es más pequeño que al anterior, quedará basura en el final del archivo, para evitar esto puede usar el comando CREATE después del WRITE

Errores

Mensaje Descripción

Acceso denegado ( -Cuando el acceso a la carpeta no esta permitido, o se le niega los permisos en carpetas anteriores. -Si no existe y es abierto por el comando WRITE.

El archivo es una carpeta (

FileName se refiere a un directorio. Para ello use la función Dir.

El archivo o carpeta no existe (

FileName No existe, o el directorio no existe o es un enlace simbólico.

Memoria insuficiente (1)

Si el sistema se quedó sin memoria.

error/ful l Si donde iba a ser creado el FileName no hay espacio.

No se trata de una carpeta... (

Si un componente es usado para un archivo y se encuentra en un directorio.

Error del sistema... ( Otros posibles errores:

• Si se encuantran muchos enlaces simbolicos en la solucion de FileName.

• Si el proceso está al maximo de archivos abiertos. • Si se llega al máximo de archivos abiertos soportados por el sistema. • FileName se refiere a un dispositivo especifico que no esta montado en

ese momento. • Si el FileName es una tubería pipe Y el proceso no puede abrirlo para

leerlo. • FileName Si el archivo es solo lectura y el archivo ocupe escribirse.

• FileName Si se refiere a una imagen ejecutable que se encuentra actualmente en ejecución y se pidió el acceso de escritura.

Example

' Escribir el contenido de un archivo de texto en la pantalla

DIM hFile AS FileDIM sLine AS String

hFile = OPEN "/etc/passwd" FOR INPUT

WHILE NOT Eof(hFile) LINE INPUT #hFile, sLine PRINT sLineWEND

' Ver un puerto serial

DIM hFile AS File

hFile = OPEN "/dev/ttyS0" FOR READ WRITE WATCH

...

PUBLIC SUB File_Read()

DIM iByte AS Byte

READ #hFile, iByte PRINT "Got one byte: "; iByte

END

' Leer de un archivo BMP, sabiendo que usa el formato little-endian:

DIM hFile AS FileDIM iData AS Integer

hFile = OPEN "image.bmp" FOR INPUThFile.ByteOrder = gb.LittleEndian...READ #hFile, iData

Véase también

Flujos y funciones de Entrada/Salida, Funciones para Archivos y Carpetas, Stream

DFree

Size = DFree ( Ruta )

Devuelve el espacio libre (en bytes) del dispositivo cuya Ruta se indica.

Example

PRINT DFree("/")

5112569856

PRINT DFree("/home")

454918144

Véase también

Funciones para Archivos y Carpetas

Dir

No_mbre del array = Dir ( _Directorio AS String [ , Patrón AS String , Filtro AS Integer ] ) AS String[]

Returns a string array that contains the names of files located in Directory that matches the Pattern and the Filter. regresa una array string con los nombres de los archivos que contenga el Directorio que cumplan con el patrón y con el filtro.

• El patrón puede contener los mismos caracteres genéricos que el LIKEoperador. Si no se especifica el patrón, todas las archivos son devueltos.

• The filter specifies what kind of files will be returned, by specifying one or a combination of the file type constants. If Filter is not specified, all files and directories are returned.

• El filtro especifica qué tipo de archivos le serán devueltos, especificando uno o una combinación de los file type constants. Si el Filtro no es especificado, todos los archivos y directorios son devueltos.

Los archivos devueltos son relativos, los directorios pueden no contener los archivos buscados

Example

' Imprime las imagenes png de un directorio, en orden alfabetico

SUB PrintDirectory(Directory AS String)

DIM File AS String

FOR EACH File IN Dir(Directory, "*.png").Sort() PRINT File NEXT

END

Véase también

Funciones para Archivos y Carpetas

IsDir

Booleano = IsDir ( Ruta )Booleano = Dir? ( Ruta )

Devuelve si una ruta apunta a una carpeta.

Si la ruta no existe, esta función devuelve FALSE.

Example

PRINT IsDir("/etc/password")

False

PRINT IsDir(User.Home &/ ".kde")

True

PRINT IsDir("/windows")

False

KILL

KILL Ruta

Elimina un archivo existente.

Si quiere eliminar una carpeta, emplee RMDIR.

Example

TRY KILL "/tmp/testfile"

LINK

LINK Ruta origen TO Ruta destino

Crea un enlace simbólico llamado Ruta destino que apunta a la carpeta o fichero Ruta origen.

Véase también

Funciones para Archivos y Carpetas

MKDIR

MKDIR Ruta

Crea una carpeta.

Si alguna de las carpetas padre de la que se desea crear no existe, el comando fallará.

Errores

Mensaje Descripción

Acceso denegado ( La carpeta padre no tiene permiso de escritura para el proceso, o una de las carpetas dentro de la Ruta no tiene permiso de consulta.

El archivo o carpeta no existe (

Una de las carpetas que componen la Ruta no existe, o es un enlace simbólico roto.

No se trata de una carpeta... (

Uno de los componentes empleados en la Ruta, no es una carpeta.

Memoria insuficiente (1)

Memoria insuficiente en el núcleo (kernel).

Nombre de archivo demasiado largo (

Ruta demasiado larga.

Dispositivo lleno ( El dispositivo que contiene la Ruta no dispone de espacio libre.

El archivo ya existe ( La Ruta ya existe (no necesariamente como carpeta). Esto incluye el caso de que sea un enlace simbólico, roto o no.

Error del sistema... ( Otros posibles errores del sistema:

• Demasiados enlaces simbólicos encontrados a lo largo de Ruta. • El sistema de archivos que contiene la Ruta no soporta la creación

de carpetas. • Ruta se refiere a una carpeta dentro de un sistema de archivos de

sólo lectura.

RDir

FileNameArray = RDir ( Directory AS String [ , Pattern AS String , Filter AS Integer ] ) AS String[]

Returns a string array that contains the names of files located in Directory and its sub-directories that matches the Pattern and the Filter.

The specified directory is recursed.

The pattern can contain the same generic characters than the LIKE operator. If no pattern is specified, any file name is returned.

The filter specifies what kind of files will be returned.

The filter can be one of the following values:

• gb.File for returning only files. • gb.Directory for returning only directories. • gb.File + gb.Directory for returning both.

If Filter is not specified, all files and directories are returned.

The file paths returned are relative to the searched directory.

Example

' Print the png image files in a directory and its sub-directories

SUB PrintDirectory(Directory AS String)

DIM File AS String

FOR EACH File IN RDir(Directory, "*.png") PRINT File NEXT

END

Véase también

Funciones para Archivos y Carpetas

MOVE

MOVE Antiguo Nombre TO Nuevo nombre

Renombra o mueve un archivo o carpeta.

Antiguo nombre y Nuevo nombre pueden estar situados en diferentes carpetas, pero deben pertenecer al mismo dispositivo.

Si desea mover un archivo cualquiera que sea su ubicación, haga lo siguiente:

TRY MOVE OldName TO NewName IF ERROR THEN TRY COPY OldName TO NewName IF NOT ERROR THEN KILL OldName ENDIF

RMDIR

RMDIR Ruta

Elimina una carpeta especificada por Ruta.

La carpeta ha de estar vacía.

Stat

Informción Archivo = Stat ( Ruta )

Devuelve información sobre un archivo o carpeta como el objeto virtual .Stat:

• Tipo de archivo, es decir, archivo normal, carpeta, tubería con nombre... • Tamaño del archivo. • Fecha y hora de la última modificación. • Permisos. • ...

Example

WITH Stat("/home") PRINT .Type = gb.Directory PRINT Round(.Size / 1024); "K"END WITH

True4K

Temp$

Nombre archivo = Temp$( [ Nombre ] )Nombre archivo = Temp( [ Nombre ] )

Devuelve una ruta para un archivo temporal.

Las rutas tienen esta forma:

/tmp/gambas.[id Usuario]/[id Proceso]/[Nombre].tmp

Donde [id Usuario] es el identificador del usuario en el sistema (UID), [id Proceso] es el identificador del sistema para el proceso en curso (PID), y [Nombre] es el valor del argumento Nombre.

Si no se especifica Nombre, es reemplazado por un número entero incrementado cada vez que se llama a la función. De esta forma, se asegura que disponga de nombres no duplicados.

Todos los archivos situados en la carpeta /tmp/gambas.[id Usuario]/[id Proceso] se eliminan automáticamente al finalizar el programa Gambas.

Example

PRINT Temp$()

/tmp/gambas.501/14593/1.tmpPRINT Temp$()

/tmp/gambas.501/14593/2.tmpPRINT Temp$("version")

/tmp/gambas.501/14593/version.tmp