FileSys, Threads, O/S   (hApi unit)

_Valid_Path

Ensures that a given path string ends with a backslash (`\`).
If the input path does not end with a backslash, one is appended.
function _Valid_Path(Path: String): String;

Parameters

  • Path: String; The input path to validate.

Return Value

Returns the corrected path string, ensuring it ends with a backslash (`\`).

GetAppPath

Retrieves the directory path where the application is running from.
function GetAppPath: String;

Return Value

Returns the full path of the application directory.
If retrieval fails, an empty string is returned.

ExtractFileExtW

Extracts the file extension from a given filename.
It returns the extension in lowercase and excludes the leading period (`.`).
function ExtractFileExtW(FileName: String): String;

Parameters

  • FileName: String; The full filename including extension.

Return Value

Returns the extracted file extension in lowercase.
If no extension is found, an empty string is returned.

ExtractFileNameW

Extracts the filename from a given full file path.
It optionally includes or excludes the file extension.
function ExtractFileNameW(CONST FileName: String; CONST Include_Ext: Boolean): String;

Parameters

  • FileName: String; The full file path.
  • Include_Ext: Boolean; If `True`, includes the file extension. If `False`, returns only the filename without extension.

Return Value

Returns the extracted filename, optionally with or without its extension.
Returns an empty string if extraction fails.

ExtractFilePathW

Extracts the directory path from a given filename.
function ExtractFilePathW(FileName: String): String;

Parameters

  • FileName: String; The full file path including the filename.

Return Value

Returns the extracted directory path.
If no directory path is found, an empty string is returned.

ReplaceFileExtW

Replaces the file extension of a given filename while preserving the path.
If no extension exists, the new extension is appended.
function ReplaceFileExtW(CONST FileName, NewExt: String): String;

Parameters

  • FileName: String; The full file path.
  • NewExt: String; The new file extension (without the leading `.`).

Return Value

Returns the filename with the updated extension.
If no extension exists, the new extension is appended.

Play_Wave_ASync

Plays a WAV audio file asynchronously.
It supports looping playback and ensures the file exists before attempting to play it.
procedure Play_Wave_ASync(FileName: String; ON_LOOP: Boolean = False);

Parameters

  • FileName: String; The path to the WAV file to be played.
  • ON_LOOP: Boolean; If `True`, the audio will loop continuously until stopped.
If `he_Enable_Play_Wave_ASync` is disabled or the file does not exist, it exits without playing the audio.

Stop_All_Waves

Stops all currently playing WAV files asynchronously.
If a specific file is provided, it stops only that file.
procedure Stop_All_Waves(FileName: String = '');

Parameters

  • FileName: String; The specific WAV file to stop playback. If empty, all WAV files will be stopped.
If `FileName` is provided and does not exist, no action is taken.

Form_On_Monitor

Positions a form on a specific monitor.
It adjusts the form's size and style to fit the selected monitor.
procedure Form_On_Monitor(Form: TForm; MonitorIndex: Byte; FormStyle: TFormStyle = FsStayOnTop);

Parameters

  • Form: TForm; The form to position on the specified monitor.
  • MonitorIndex: Byte; The index of the monitor to position the form on.
  • FormStyle: TFormStyle; The form style to apply. Default is `FsStayOnTop`.
If `MonitorIndex` is out of bounds, the procedure exits without repositioning the form.

Init_Dialog_Form_Position

Initializes the screen position and layout of a dialog form according to optional layout rules.
Can enforce maximum width or full maximization, with optional width limitation.
Procedure Init_Dialog_Form_Position(Form: TForm; Max_Width: Boolean = False; Maximized: Boolean = False; Max_Width_Limit: Word = 1600);

Parameters

  • Form: TForm; the form whose position and size are to be initialized.
  • Max_Width: Boolean; if True, restricts the form width to Max_Width_Limit.
  • Maximized: Boolean; if True, sets the form window to maximized state.
  • Max_Width_Limit: Word; the maximum width in pixels to apply when Max_Width is enabled.

GetParentFormFrame

Retrieves the nearest parent scrolling form or frame for a given control.
It iterates through the control hierarchy to find the first `TScrollingWinControl`.
function GetParentFormFrame(Control: TControl): TScrollingWinControl;

Parameters

  • Control: TControl; The control for which to find the parent form frame.

Return Value

Returns the nearest `TScrollingWinControl` found in the control hierarchy.
If no parent frame is found, returns `NIL`.

GetParent_TOP_Frame

Retrieves the topmost `TFrame` in the control hierarchy.
It searches through parent controls until it finds the highest-level `TFrame`.
function GetParent_TOP_Frame(Control: TControl): TFrame;

Parameters

  • Control: TControl; The control for which to find the topmost frame.

Return Value

Returns the highest-level `TFrame` found in the hierarchy.
If no frame is found, returns `NIL`.

GetParent_TOP_Form

Retrieves the topmost `TForm` in the control hierarchy.
It searches through parent controls until it finds the highest-level `TForm`.
function GetParent_TOP_Form(Control: TControl): TForm;

Parameters

  • Control: TControl; The control for which to find the topmost form.

Return Value

Returns the highest-level `TForm` found in the hierarchy.
If no form is found, returns `NIL`.

SetKeyboardLayout

Sets the active keyboard layout for the application.
procedure SetKeyboardLayout(CONST Local_Lang: Boolean);

Parameters

  • Local_Lang: Boolean; If `True`, sets the keyboard layout to the local translation language. If `False`, switches to the English layout.
It changes the keyboard layout based on the specified language settings.

SetKeyboardLayout_Own

Allows setting either the default or a custom keyboard layout.
procedure SetKeyboardLayout_Own(CONST Local_Lang: Boolean; CONST OwnTrans: ThObject_Own_Translation);

Parameters

  • Local_Lang: Boolean; If `True`, switches to the local translation language.
  • OwnTrans: ThObject_Own_Translation; Custom translation object that controls own keyboard layout behavior.
It modifies the keyboard layout according to the provided settings.

Lock_Thread_By_Token

Attempts to acquire a lock for thread synchronization.
function Lock_Thread_By_Token(VAR Token: Boolean; Wait_Ms: Integer = 250): Boolean;

Parameters

  • Token: Boolean; A shared boolean token used for synchronization.
  • Wait_Ms: Integer; The maximum time in milliseconds to wait for the token. Default is `250`.

Return Value

Returns `True` if the token was successfully acquired.
Returns `False` if the lock was not acquired within the wait period.

Wait_For_Thread_Token

Waits until a thread token becomes available.
function Wait_For_Thread_Token(VAR Token: Boolean; Wait_Ms: Integer = 250): Boolean;

Parameters

  • Token: Boolean; The shared synchronization token.
  • Wait_Ms: Integer; The time in milliseconds to wait for the token. Minimum value is `5`.

Return Value

Returns `True` if the token is released within the wait time.
Returns `False` if the token remains locked after the timeout period.

Free_And_NIL

Safely frees an object and sets its reference to `NIL`.
procedure Free_And_NIL(VAR Obj);

Parameters

  • Obj: VAR; A reference to the object to be freed.
If the object is valid, it is freed and its reference is set to `NIL` to prevent access violations.

DebugMode

Checks whether the application is running in debug mode.
It utilizes conditional compilation to determine the state of `DebugHook`.
function DebugMode: Boolean;

Return Value

Returns `True` if the application is running in debug mode (`DebugHook > 0`).
Returns `False` otherwise.

IS_Main_Thread

Checks whether the current code is running on the main UI thread.
function IS_Main_Thread: Boolean;

Return Value

Returns `True` when called from the main thread.
Returns `False` when called from a worker/background thread.

Main_Thread_App_PM

Processes application messages from the main thread context.
procedure Main_Thread_App_PM;

Return Value

This procedure does not return a value.

Sync_Proc

Executes a thread procedure in synchronized context and reports success.
function Sync_Proc(_Procedure: TThreadProcedure; CONST App_PM: Byte = 0): Boolean;

Parameters

  • _Procedure: TThreadProcedure; The code block to execute in synchronized context.
  • App_PM: Byte; Optional message-processing mode flag (default is `0`).

Return Value

Returns `True` when code execution completed successfully.
Returns `False` if execution failed.

Run_Code_Under_Thread

Runs a supplied procedure under a worker thread.
procedure Run_Code_Under_Thread(_Procedure: TThreadProcedure);

Parameters

  • _Procedure: TThreadProcedure; The code block to execute on a thread.