Harbour MiniGUI Extended and the Win32 API: A Technical Deep Dive
135 views
Skip to first unread message
Grigory Filatov
Feb 14, 2025, 5:19:56 AM2/14/25
to Harbour Minigui
Hi Friends,
I would like to introduce this technical manual which was received from Gemini AI with my small corrections.
Harbour MiniGUI Extended (HMG Extended) is a powerful, open-source development environment based on the Harbour compiler and the MiniGUI graphics library. While
Harbour provides a platform-independent abstraction layer for GUI development, HMG Extended leverages the underlying operating system's API for enhanced performance, features, and access to system resources. This manual focuses on how HMG Extended integrates with the Win32 API on Windows platforms, providing a technical understanding of the mechanisms involved.
1. Understanding the Abstraction Layer:
HMG Extended aims to provide a high-level, object-oriented programming model that shields developers from the complexities of the Win32 API. However, it doesn't completely hide it. Instead, it offers a carefully crafted abstraction layer that allows developers to:
* Utilize HMG Extended's built-in controls and functions: These are implemented using Win32 API calls under the hood, providing a consistent interface.
* Directly access the Win32 API when necessary: For advanced features, custom controls, or specific system interactions, HMG Extended provides mechanisms to directly call Win32 functions.
This approach allows developers to choose the level of abstraction they need, balancing ease of use with the power and flexibility of the Win32 API.
2. Core Integration Mechanisms:
HMG Extended integrates with the Win32 API through several key mechanisms:
* Function Pointers and DLL Calls: The primary method for accessing Win32 functions is through function pointers and Dynamic Link Library (DLL) calls. HMG Extended provides a mechanism to declare and call functions residing in Win32 DLLs (e.g., user32.dll, kernel32.dll, gdi32.dll).
* Declaration: The DECLARE keyword is used to declare external functions residing in DLLs. The syntax typically involves specifying the function name, the DLL it resides in, and the data types of the arguments and return value.
DECLARE MessageBoxA( HWND, LPCSTR, LPCSTR, UINT ) IN user32.dll ALIAS MessageBox
This declares the MessageBoxA function from user32.dll as MessageBox within the Harbour environment. HWND, LPCSTR, and UINT are data types that map to their Win32 counterparts.
* Calling: Once declared, the function can be called like any other Harbour function.
LOCAL hWnd := 0 // NULL handle for the parent window
LOCAL lpText := "Hello from HMG Extended!"
LOCAL lpCaption := "Win32 API Example"
LOCAL uType := 0 // MB_OK flag
MessageBox( hWnd, lpText, lpCaption, uType )
This code snippet calls the MessageBoxA function, displaying a simple message box.
* Data Type Mapping: HMG Extended provides a mapping between Harbour data types and their corresponding Win32 data types. This is crucial for ensuring correct data passing between the Harbour environment and the Win32 API.
* Numeric Types: Harbour's numeric types (e.g., NUMERIC, INT) are mapped to Win32 integer types (e.g., INT, LONG, DWORD).
* Character Strings: Harbour's character strings (CHARACTER) are mapped to Win32 string types (e.g., LPCSTR, LPWSTR). Care must be taken to handle ANSI (A) and Unicode (W) versions of Win32 functions correctly. HMG Extended often provides helper functions or macros to simplify this.
* Handles: Win32 handles (e.g., HWND, HDC, HMODULE) are typically represented as numeric values in Harbour.
* Structures: HMG Extended allows defining structures that mirror Win32 structures. This is essential for passing complex data to and from Win32 functions. The STRUCT keyword is used to define these structures.
STRUCT RECT
LONG left
LONG top
LONG right
LONG bottom
END STRUCT
* Window Handles (HWND): HMG Extended provides access to the underlying Win32 window handles (HWND) for its controls. This allows developers to directly manipulate the Win32 window properties and behavior.
* GetControlHandle() Function: The GetControlHandle() function is used to retrieve the Win32 window handle associated with an HMG Extended control.
LOCAL hWnd := GetControlHandle(MyControl, MyWin)
* Direct Manipulation: Once the HWND is obtained, developers can use Win32 API functions like SetWindowPos(), GetWindowRect(), SendMessage(), etc., to directly interact with the window.
* Window Procedures (WndProc): HMG Extended allows developers to define custom window procedures (WndProc) for handling window messages. This provides fine-grained control over the behavior of HMG Extended windows.
* Subclassing: HMG Extended uses window subclassing to intercept and process window messages. This involves replacing the default window procedure with a custom one.
* Message Handling: The custom WndProc receives window messages (e.g., WM_PAINT, WM_MOUSEMOVE, WM_KEYDOWN) and can process them as needed. The WndProc can then call the original window procedure (using CallWindowProc()) to handle the message in the default way.
* Callbacks: Many Win32 API functions require callback functions to be passed as arguments. HMG Extended supports the use of Harbour functions as callbacks.
* Declaration: The callback function must be declared with the correct signature (argument types and return type) to match the requirements of the Win32 API function.
* Passing the Callback: The Harbour function can then be passed as an argument to the Win32 API function. HMG Extended handles the necessary conversion and marshaling of data between the Harbour environment and the Win32 API.
3. Examples of Win32 API Integration in HMG Extended:
* Custom Drawing: Using the WM_PAINT message and the HDC (Device Context) obtained from the BeginPaint() and EndPaint() functions, developers can perform custom drawing on HMG Extended controls.
* System Information: Accessing system information using functions like GetLocaleInfo(), GetWindowsDirectory(), GetComputerName(), etc.
* Registry Access: Reading and writing to the Windows Registry using functions like RegOpenKeyEx(), RegQueryValueEx(), RegSetValueEx(), etc.
* Multimedia Functions: Playing audio and video using functions from the winmm.dll library.
* Networking: Using the Winsock API for network communication.
4. Considerations and Best Practices:
* Data Type Compatibility: Ensure that the data types used in Harbour code match the corresponding Win32 data types. Incorrect data types can lead to crashes or unexpected behavior.
* Memory Management: Be mindful of memory management when working with the Win32 API. Allocate and free memory appropriately to avoid memory leaks.
* Error Handling: Check the return values of Win32 API functions for errors. Use the GetLastError() function to retrieve the error code.
* Unicode Support: Pay attention to Unicode support. Use the W (Unicode) versions of Win32 functions when necessary.
* Documentation: Refer to the official Win32 API documentation for detailed information about the functions and data types.
* HMG Extended Documentation: Consult the HMG Extended documentation for specific examples and best practices related to Win32 API integration.
5. Conclusion:
HMG Extended provides a powerful and flexible framework for developing Windows applications. Its integration with the Win32 API allows developers to leverage the full power of the Windows operating system while benefiting from the ease of use and productivity of the Harbour language and the MiniGUI library. By understanding the core integration mechanisms and following best practices, developers can effectively utilize the Win32 API to create sophisticated and feature-rich applications with HMG Extended. This manual provides a foundation for further exploration and experimentation with the Win32 API within the HMG Extended environment. Remember to consult the official documentation for both HMG Extended and the Win32 API for the most up-to-date information and detailed examples.
1. Understanding the Abstraction Layer:
HMG Extended aims to provide a high-level, object-oriented programming model that shields developers from the complexities of the Win32 API. However, it doesn't completely hide it. Instead, it offers a carefully crafted abstraction layer that allows developers to:
* Utilize HMG Extended's built-in controls and functions: These are implemented using Win32 API calls under the hood, providing a consistent interface.
* Directly access the Win32 API when necessary: For advanced features, custom controls, or specific system interactions, HMG Extended provides mechanisms to directly call Win32 functions.
This approach allows developers to choose the level of abstraction they need, balancing ease of use with the power and flexibility of the Win32 API.
2. Core Integration Mechanisms:
HMG Extended integrates with the Win32 API through several key mechanisms:
* Function Pointers and DLL Calls: The primary method for accessing Win32 functions is through function pointers and Dynamic Link Library (DLL) calls. HMG Extended provides a mechanism to declare and call functions residing in Win32 DLLs (e.g., user32.dll, kernel32.dll, gdi32.dll).
* Declaration: The DECLARE keyword is used to declare external functions residing in DLLs. The syntax typically involves specifying the function name, the DLL it resides in, and the data types of the arguments and return value.
DECLARE MessageBoxA( HWND, LPCSTR, LPCSTR, UINT ) IN user32.dll ALIAS MessageBox
This declares the MessageBoxA function from user32.dll as MessageBox within the Harbour environment. HWND, LPCSTR, and UINT are data types that map to their Win32 counterparts.
* Calling: Once declared, the function can be called like any other Harbour function.
LOCAL hWnd := 0 // NULL handle for the parent window
LOCAL lpText := "Hello from HMG Extended!"
LOCAL lpCaption := "Win32 API Example"
LOCAL uType := 0 // MB_OK flag
MessageBox( hWnd, lpText, lpCaption, uType )
This code snippet calls the MessageBoxA function, displaying a simple message box.
* Data Type Mapping: HMG Extended provides a mapping between Harbour data types and their corresponding Win32 data types. This is crucial for ensuring correct data passing between the Harbour environment and the Win32 API.
* Numeric Types: Harbour's numeric types (e.g., NUMERIC, INT) are mapped to Win32 integer types (e.g., INT, LONG, DWORD).
* Character Strings: Harbour's character strings (CHARACTER) are mapped to Win32 string types (e.g., LPCSTR, LPWSTR). Care must be taken to handle ANSI (A) and Unicode (W) versions of Win32 functions correctly. HMG Extended often provides helper functions or macros to simplify this.
* Handles: Win32 handles (e.g., HWND, HDC, HMODULE) are typically represented as numeric values in Harbour.
* Structures: HMG Extended allows defining structures that mirror Win32 structures. This is essential for passing complex data to and from Win32 functions. The STRUCT keyword is used to define these structures.
STRUCT RECT
LONG left
LONG top
LONG right
LONG bottom
END STRUCT
* Window Handles (HWND): HMG Extended provides access to the underlying Win32 window handles (HWND) for its controls. This allows developers to directly manipulate the Win32 window properties and behavior.
* GetControlHandle() Function: The GetControlHandle() function is used to retrieve the Win32 window handle associated with an HMG Extended control.
LOCAL hWnd := GetControlHandle(MyControl, MyWin)
* Direct Manipulation: Once the HWND is obtained, developers can use Win32 API functions like SetWindowPos(), GetWindowRect(), SendMessage(), etc., to directly interact with the window.
* Window Procedures (WndProc): HMG Extended allows developers to define custom window procedures (WndProc) for handling window messages. This provides fine-grained control over the behavior of HMG Extended windows.
* Subclassing: HMG Extended uses window subclassing to intercept and process window messages. This involves replacing the default window procedure with a custom one.
* Message Handling: The custom WndProc receives window messages (e.g., WM_PAINT, WM_MOUSEMOVE, WM_KEYDOWN) and can process them as needed. The WndProc can then call the original window procedure (using CallWindowProc()) to handle the message in the default way.
* Callbacks: Many Win32 API functions require callback functions to be passed as arguments. HMG Extended supports the use of Harbour functions as callbacks.
* Declaration: The callback function must be declared with the correct signature (argument types and return type) to match the requirements of the Win32 API function.
* Passing the Callback: The Harbour function can then be passed as an argument to the Win32 API function. HMG Extended handles the necessary conversion and marshaling of data between the Harbour environment and the Win32 API.
3. Examples of Win32 API Integration in HMG Extended:
* Custom Drawing: Using the WM_PAINT message and the HDC (Device Context) obtained from the BeginPaint() and EndPaint() functions, developers can perform custom drawing on HMG Extended controls.
* System Information: Accessing system information using functions like GetLocaleInfo(), GetWindowsDirectory(), GetComputerName(), etc.
* Registry Access: Reading and writing to the Windows Registry using functions like RegOpenKeyEx(), RegQueryValueEx(), RegSetValueEx(), etc.
* Multimedia Functions: Playing audio and video using functions from the winmm.dll library.
* Networking: Using the Winsock API for network communication.
4. Considerations and Best Practices:
* Data Type Compatibility: Ensure that the data types used in Harbour code match the corresponding Win32 data types. Incorrect data types can lead to crashes or unexpected behavior.
* Memory Management: Be mindful of memory management when working with the Win32 API. Allocate and free memory appropriately to avoid memory leaks.
* Error Handling: Check the return values of Win32 API functions for errors. Use the GetLastError() function to retrieve the error code.
* Unicode Support: Pay attention to Unicode support. Use the W (Unicode) versions of Win32 functions when necessary.
* Documentation: Refer to the official Win32 API documentation for detailed information about the functions and data types.
* HMG Extended Documentation: Consult the HMG Extended documentation for specific examples and best practices related to Win32 API integration.
5. Conclusion:
HMG Extended provides a powerful and flexible framework for developing Windows applications. Its integration with the Win32 API allows developers to leverage the full power of the Windows operating system while benefiting from the ease of use and productivity of the Harbour language and the MiniGUI library. By understanding the core integration mechanisms and following best practices, developers can effectively utilize the Win32 API to create sophisticated and feature-rich applications with HMG Extended. This manual provides a foundation for further exploration and experimentation with the Win32 API within the HMG Extended environment. Remember to consult the official documentation for both HMG Extended and the Win32 API for the most up-to-date information and detailed examples.
Hope this is useful.
Regards,
Grigory
Reply all
Reply to author
Forward
0 new messages