Manuales For-Next.

APIs (III) Ejemplo de uso.

Para este ejemplo de uso vamos a trabajar con la función API SetWindowPos, esta función manipula las ventanas abiertas en el escritorio, usada para mantener un formulario en pantalla sin ser ocultado por otras aplicaciones.

Algunos de los párametros usados en las APIs, son utilizados para definir el comportamiento de la función e incidir en los datos devueltos.

      Public Declare Function SetWindowPos Lib "user32" (ByVal hwnd As Long, _
      ByVal hWndInsertAfter As Long, ByVal x As Long, ByVal y As Long, _
      ByVal cx As Long, ByVal cy As Long, ByVal wFlags As Long) As Long

Parámetros usados por la función.

Tipo	Nombre	Uso
HWND	hWnd	Manipulador asignado a la ventana, define la ventana (Form) sobre el que vamos a actuar.
HWND	hWndInsertAfter	Valor que queremos asignar en el Z-order* de la ventana con respento al escritorio de Windows.
Integer	X	Posición horizontal
Integer	Y	Posición vertical
Integer	cx	Ancho
Integer	cy	Alto
UINT**	wFlags	Modificador de la posición para la ventana, controla el comportamiento de la función.
() Coordenada de profundidad para el orden de las ventanas en el escritorio. (*) UINT Integer de 16-bit sin signo en Windows versions 3.0 y 3.1, en Win32 es un Integer de 32-bit sin signo.

Se observa por los parámetros usados, que podemos actuar, tanto sobre el eje Z (hWndInsertAfter) para posicionar nuestro formulario en el primer plano, como con su posicionamiento y tamaño con X, Y, cx y cy. La forma en que obtengamos los resultados, viene definida por el parámetro de nombre wFlags. Usando los valores de constantes definidos para este parámetro, podemos actuar sobre el resultado.

Algunas de estas constantes son:

Nombre	Uso
Posición Z-order definidas en hWndInsertAfter
HWND_BOTTOM	Situa Z-order al final. si el valor hWnd identifica una ventana que está en primer plano la enviará al final de todas las ventanas.
HWND_NOTOPMOST	Coloca la ventana en una posición relativa de orden que no es la primera( pasa a un estado normal de uso donde puede obtener el foco o pasar al siguiente plano. ).
HWND_TOP	Posiciona el formulario en primer plano de la lista del Z-order.
HWND_TOPMOST	Coloca la ventana delante de todas las ventanas que ocupen un primer plano, fuerza a que sea la ventana primera de todas las demás.
Conportamiento de SetWindowPos según wFlags
SWP_HIDEWINDOW	Oculta la ventana.
SWP_NOMOVE	Mantiene la ventana en la misma posición, ignorando los parámetros x e y del fomulario.
SWP_NOOWNERZORDER	Descarta el cambio de la posición Z-order.
SWP_NOSIZE	No modifica el tamaño de la ventana, ignora el parámetro pasado en cx y cy.

Como se ve en este ejemplo, la función usada para ordenar el Z-order del escritorio en base a las ventanas abiertas, se ve alterado en su uso por el parámetro wFlags.

Para probar esta función, la tenemos que declarar en un módulo *.bas junto con las constante para su uso.

      Option Explicit

      Public Declare Function SetWindowPos Lib "user32" (ByVal hwnd As Long, _
      ByVal hWndInsertAfter As Long, ByVal x As Long, ByVal y As Long, _
      ByVal cx As Long, ByVal cy As Long, ByVal wFlags As Long) As Long
      'primer plano
      Public Const HWND_TOPMOST = -1
      'normal
      Public Const HWND_NOTOPMOST = -2
      'estas dos constantes son para que al ejecutar
      'la función no varie su tamaño y posición.
      Public Const SWP_NOSIZE = &H1
      Public Const SWP_NOMOVE = &H2

Luego añadiremos dos funciones definidas por el usuario para el manejo de la función SetWindowPos.

'Coloca el formulario delante de los demás formularios.
Public Sub FormPrimerPlano(frm As Form)
Call SetWindowPos(frm.hwnd, HWND_TOPMOST, 0, 0, 0, 0, SWP_NOMOVE Or SWP_NOSIZE)
End Sub

'Libera la función para poder modificar su posición en el orden de ventanas.
Public Sub FormNormal(frm As Form)
Call SetWindowPos(frm.hwnd, HWND_NOTOPMOST, 0, 0, 0, 0, SWP_NOMOVE Or SWP_NOSIZE)
End Sub

A continuación pegaremos tres CommandButton y un Label en el Form1 y le asignaremos el siguiente código a los eventos Click de éstos.

      Option Explicit

      Private Sub Command1_Click()
            FormPrimerPlano Me
            Label1 = "El formulario se muestra en primer plano y no será ocultado por otras ventanas"
      End Sub

      Private Sub Command2_Click()
            FormNormal Me
            Label1 = "El formulario se muestra de forma normal"
      End Sub

      Private Sub Command3_Click()
            Unload Me
      End Sub

Una vez hecho ésto ejecutar la aplicación tomando como formulario inicial Form1.

Al pulsar Command1 el formulario se mantendrá en primer plano, aún cuando otra ventana o aplicación tenga el foco de ejecución.

Al pulsar Command2 el formulario se volverá a quedar liberado y se ocultará cuando otra ventana o aplicación obtenga el foco de ejecución.

Al pulsar Command3 salimos de la ejecución.

En el apartado Demos tienes el ejemplo para bajarlo