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 (`\`).

_Valid_Filename

Returns a filename without a path when it detects ..\, ../, a drive root, or a UNC prefix.
Function _Valid_Filename(FN: String): String;
This is a limited path traversal filter. Validate the returned name for your intended file operation.

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);

Parameters

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

Get_First_Parent_Form_or_Frame

Finds the nearest parent form or frame of a control. Returns nil if none exists.
Function Get_First_Parent_Form_or_Frame(Control: TControl): TScrollingWinControl;

Get_First_Parent_Form

Finds the parent form of a control. A control that is itself a TForm returns itself.
Function Get_First_Parent_Form(Control: TControl): TForm;

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; CONST 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.

Lock_Object_By_Thread

Attempts to enter an object's monitor, waiting at least 5 milliseconds and up to Wait_Ms.
Function Lock_Object_By_Thread(CONST AObject: TObject; Wait_Ms: Cardinal = 250): Boolean;
Returns True only if the monitor was entered. Call Release_Object_By_Thread after a successful lock.

Release_Object_By_Thread

Leaves a monitor previously entered on the same object and thread.
Procedure Release_Object_By_Thread(CONST AObject: TObject);

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.