<?xml version="1.0" encoding="UTF-8"?>
<!--

Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus 
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0 
International public license.

https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
file://../../cc-by-sa-4-0.txt

Copyright (c) 1997-2023, by the Lazarus Development Team.

-->
<fpdoc-descriptions>
<package name="lcl">
<!--
====================================================================
LCLPlatformDef
====================================================================
-->
<module name="LCLPlatformDef">
<short>Contains routines and types used in LCL Platform definitions.</short>
<descr>
<p>
<file>lclplatformdef.pas</file> contains types, constants, variables and
routines used in LCL platform definitions.
</p>
<p>
<file>lclplatformdef.pas</file> is part of the Lazarus Component Library 
(<b>LCL</b>).
</p>
</descr>

<element name="TLCLPlatform">
<short>Represents the supported platforms for the LCL.</short>
<descr/>
<seealso>
<link id="LCLPlatformDirNames"/>
<link id="TLCLPlatforms"/>
</seealso>
</element>
<element name="TLCLPlatform.lpGtk">
<short>GIMP ToolKit.</short>
</element>
<element name="TLCLPlatform.lpGtk2">
<short>GTK version 2.</short>
</element>
<element name="TLCLPlatform.lpGtk3">
<short>GTK version 3.</short>
</element>
<element name="TLCLPlatform.lpWin32">
<short>Windows API (née Win32 API).</short>
</element>
<element name="TLCLPlatform.lpWinCE">
<short>Windows CE.</short>
</element>
<element name="TLCLPlatform.lpCarbon">
<short>macOS Carbon API.</short>
</element>
<element name="TLCLPlatform.lpQT">
<short>QT version 4.</short>
</element>
<element name="TLCLPlatform.lpQt5">
<short>QT version 5.</short>
</element>
<element name="TLCLPlatform.lpfpGUI">
<short>FreePascal GUI.</short>
</element>
<element name="TLCLPlatform.lpNoGUI">
<short>No GUI.</short>
</element>
<element name="TLCLPlatform.lpCocoa">
<short>macOS Cocoa API.</short>
</element>
<element name="TLCLPlatform.lpCustomDrawn">
<short>Custom-drawn.</short>
</element>
<element name="TLCLPlatform.lpMUI">
<short>Magic User Interface (MUI) for AmigaOS, AROS.</short>
</element>

<element name="TLCLPlatforms">
<short>Set type used to store TLCLPlatform enumeration value(s).</short>
<descr/>
<seealso>
<link id="TLCLPlatform"/>
</seealso>
</element>

<element name="DirNameToLCLPlatform">
<short>
Gets the platform enumeration value for the specified directory name.
</short>
<descr>
<p>
DirNameToLCLPlatform is a TLCLPlatform function used to get the platform
identifier for the source directory specified in the ADirName argument. It is
assumed that ADirName contains only the directory name relative to
($LazarusDir)/lcl/interfaces without path delimiters. In other words, a value
like: 'win32', 'qt5', or 'gtk3'.
</p>
<p>
DirNameToLCLPlatform performs a case-insensitive comparison between ADirName
and each of the values in the LCLPlatformDirNames constant. The return value
is the enumeration value which identifies the platform and widgetset for the
specified directory.
</p>
<p>
If a matching value in LCLPlatformDirNames is not found, the return value is
set to lpGtk2.
</p>
<p>
DirNameToLCLPlatform is called from the <file>lazbuild</file> utility when a
widgetset override has been provided on the command line.
</p>
</descr>
<seealso>
<link id="LCLPlatformDirNames"/>
<link id="TLCLPlatform"/>
</seealso>
</element>
<element name="DirNameToLCLPlatform.Result">
<short>TLCLPlatform enumeration value for the given directory name.</short>
</element>
<element name="DirNameToLCLPlatform.ADirName">
<short>Directory name to convert to a TLCLPlatform enumeration value.</short>
</element>

<element name="DirNameToDisplayName">
<short>
Gets the descriptive name for the LCL widgetset located in the specified 
directory name.
</short>
<descr>
<p>
<var>DirNameToDisplayName</var> is <var>String</var> function used to get the 
descriptive name associated with the specified widgetset directory name.
</p>
<p>
<var>ADirName</var> contains the widgetset directory handled in the routine. 
It is not a full path - or even a relative path - it simply a directory name 
like 'qt5' or 'win32'.
</p>
<p>
DirNameToDisplayName calls DirNameToLCLPlatform to get the TLCLPlatform 
enumeration value for the widgetset directory. If ADirName is not found, the 
lpGtk2 platform is assumed. The enumeration value is used an an index into the 
LCLPlatformDisplayNames constant where the return value is stored.
</p>
<p>
Use DisplayNameToDirName to convert the descriptive name back to the directory 
where the widgetset files are found.
</p>
</descr>
<version>
Added in LCL 3.0.
</version>
<seealso>
<link id="DisplayNameToDirName"/>
<link id="TLCLPlatform"/>
<link id="LCLPlatformDirNames"/>
<link id="LCLPlatformDisplayNames"/>
</seealso>
</element>
<element name="DirNameToDisplayName.Result">
<short>
Descriptive name for the specified widgetset directory.
</short>
</element>
<element name="DirNameToDisplayName.ADirName">
<short>
Widgetset directory name converted in the routine.
</short>
</element>

<element name="DisplayNameToDirName">
<short>
Gets the directory name where the widgetset files are stored for the specified 
descriptive name.
</short>
<descr>
<p>
<var>DisplayNameToDirName</var> is a <var>String</var> function used to 
convert the specified descriptive name for a widgetset to the directory where 
its files are stored.
</p>
<p>
The return value refers to a directory located in the 
<file>($LazarusDir)/lcl/interfaces</file> directory.
</p>
<p>
ADisplayName contains the descriptive name for the widgetset as returned from 
DirNameToDisplayName, and should contain a value from the 
LCLPlatformDisplayNames constant. Case is not significant for the argument 
value.
</p>
<p>
DisplayNameToDirName iterates over the values in LCLPlatformDisplayNames to 
locate the position for the value in ADisplayName. The corresponding value 
from LCLPatformDirNames is used as the return value. If the specified 
descriptive name is not found, the value 'gtk2' is used.
</p>
</descr>
<version>
Added in LCL 3.0.
</version>
<seealso>
<link id="DirNameToLCLPlatform"/>
<link id="TLCLPlatform"/>
<link id="LCLPlatformDirNames"/>
<link id="LCLPlatformDisplayNames"/>
</seealso>
</element>
<element name="DisplayNameToDirName.Result">
<short>
Directory name where the files for the specified widgetset are located.
</short>
</element>
<element name="DisplayNameToDirName.ADisplayName">
<short>
Descriptive name for the requested widgetset directory.
</short>
</element>

<element name="GetBuildLCLWidgetType">
<short>Gets the value in the BuildLCLWidgetType variable.</short>
<descr>
<p>
Used by the GetDefaultLCLWidgetType routine (in <file>interfacebase.pp</file>) 
to get the type and name for the target widgetset.
</p>
</descr>
<seealso>
<link id="BuildLCLWidgetType"/>
<link id="TLCLPlatform"/>
<link id="#lcl.interfacebase.GetDefaultLCLWidgetType">InterfaceBase.GetDefaultLCLWidgetType</link>
</seealso>
</element>
<element name="GetBuildLCLWidgetType.Result">
<short>TLCLPlatform enumeration value for the platform.</short>
</element>

<element name="LCLPlatformDirNames">
<short>
Array constant with the directory names for supported LCL platforms.
</short>
<descr>
<p>
LCLPlatformDirNames is a array of Strings with directory names for the
platforms supported for the LCL. The directory names are relative to the
($LazarusDir)/lcl/interfaces base path and should not include path delimiters.
Values in the array are indexed by TLCLPlatform enumeration values.
</p>
<p>
For example:
</p>
<code>
// var SDir, SName: String;

// SDir contains 'win32'
SDir := LCLPlatformDirNames[lpWin32];

// SName contains 'win32/win64'
SName := LCLPlatformDisplayNames[lpWin32];
</code>
<p>
Use LCLPlatformDisplayNames to get the display name for a given TLCLPlatform
enumeration value.
</p>
</descr>
<seealso>
<link id="LCLPlatformDisplayNames"/>
<link id="TLCLPlatform"/>
</seealso>
</element>

<element name="LCLPlatformDisplayNames">
<short>
Array constant with the display names for supported LCL platforms.
</short>
<descr>
<p>
LCLPlatformDisplayNames is a array of Strings with display names for the 
supported
LCL platforms. Values in the array are indexed by TLCLPlatform enumeration 
values.
For example:
</p>
<code>
// var SDir, SName: String;

// SDir contains 'win32'
SDir := LCLPlatformDirNames[lpWin32];

// SName contains 'win32/win64'
SName := LCLPlatformDisplayNames[lpWin32];
</code>
<p>
Use LCLPlatformDirNames to get the directory name for a given TLCLPlatform
enumeration value.
</p>
</descr>
<seealso>
<link id="LCLPlatformDirNames"/>
</seealso>
</element>

<element name="BuildLCLWidgetType">
<short>
Gets the TLCLPlatform enumeration value for the current platform.
</short>
<descr>
<p>
BuildLCLWidgetType is a TLCLPlatform variable with an enumeration value which
identifies the widgetset for the current platform. Its value is determined by
the compiler define active when the LCL was built. For example:
</p>
<dl>
<dt>MSWindows</dt>
<dd>Sets the variable to lpWin32.</dd>
<dt>darwin</dt>
<dd>
Sets the variable to lpCarbon for systems using the PowerPC processor.
Otherwise, the variable is set to lpCocoa.
</dd>
<dt>HASAMIGA</dt>
<dd>Sets the variable to lpMUI.</dd>
</dl>
<p>
For other platforms where a specific compiler define was not set, the
variable is set to lpGtk2.
</p>
<p>
The value in BuildLCLWidgetType is used in the <file>lazbuild</file> utility
to get the target widgetset used for the various platform defines, and when
GetDefaultLCLWidgetType is called from the LCL interface.
</p>
</descr>
<version>
For LCL version 2.2 and higher, the default widgetset for the macOS (Darwin)
platform uses the Cocoa (lpCocoa) API. For versions prior to 2.2, the default
widgetset used was the Carbon (lpCarbon) API. For Macs using the PowerPC
processor, the widgetset continues to use the Carbon (lpCarbon) API.
</version>
<seealso>
<link id="TLCLPlatform"/>
<link id="#lcl.interfacebase.GetDefaultLCLWidgetType">GetDefaultLCLWidgetType</link>
</seealso>
</element>

</module>
<!-- LCLPlatformDef -->
</package>
</fpdoc-descriptions>
