Plugin:MirLua/Module/m core: Difference between revisions

From Miranda NG
Jump to navigation Jump to search
mNo edit summary
m (more correct terminology)
Line 1: Line 1:
{{PageLang|en}}
{{PageLang|en}}
This module is imported into global table from the very beginning and is available in any module through variable '''m'''. It allows you to access basic features of Miranda NG core.
This module is imported into global table and available in any module through variable '''m'''. It allows you to access basic features of Miranda NG core.


{{Note|Parameters written in '''''bold italics''''' are obligatory.}}
{{Note|Parameters written in '''''bold italics''''' are obligatory.}}
Line 16: Line 16:
;Result
;Result
: Type: '''light userdata'''
: Type: '''light userdata'''
: Returns event descriptor if event was created successfully, else '''nil'''.
: Returns event handle if event was created successfully, otherwise '''nil'''.
;Example
;Example
{{Content:MirLua/Example|code=local hEvent = m.CreateHookableEvent('MyEvent')}}
{{Content:MirLua/Example|code=local hEvent = m.CreateHookableEvent('MyEvent')}}


=== HookEvent ===
=== HookEvent ===
Sets a callback function ("trap") to react to event call. Traps are called one by one in the order they were added to the sequence.
Sets a callback function ("hook") to react to event call. Hook are called one by one in the order they were added to the sequence.


Trap signature: <code>function (wParam, lParam) return 0 end</code>.
Hook signature: <code>function (wParam, lParam) return 0 end</code>.


Correct result for a trap is 0. When 1 is returned, the following traps in a sequence won't be called.
Correct result for a trap is 0. When 1 is returned, the following hooks in a sequence won't be called.
;Parameters
;Parameters
: '''''name'''''
: '''''name'''''
Line 32: Line 32:
: '''''hook'''''
: '''''hook'''''
:: Type: '''function'''
:: Type: '''function'''
:: Trap function to be called when event occurs.
:: Hook function to be called when event occurs.
;Result
;Result
: Type: '''light userdata'''
: Type: '''light userdata'''
: Returns trap descriptor if trap was created successfully, else '''nil'''.
: Returns trap handle if trap was created successfully, otherwise '''nil'''.
;Example
;Example
{{Content:MirLua/Example|code=local hHook = m.HookEvent('MyEvent', function(w, l)
{{Content:MirLua/Example|code=local hHook = m.HookEvent('MyEvent', function(w, l)
Line 43: Line 43:


=== UnhookEvent ===
=== UnhookEvent ===
Removes "trap" from event call sequence.
Removes hook from event call sequence.
;Parameters
;Parameters
: '''''hEvent'''''
: '''''hEvent'''''
Line 50: Line 50:
;Result
;Result
: Type: '''boolean'''
: Type: '''boolean'''
: Returns '''true''' if trap function was removed successfully, else '''false'''.
: Returns '''true''' if trap function was removed successfully, otherwise '''false'''.
;Example
;Example
{{Content:MirLua/Example|code=m.UnhookEvent(hHook)}}
{{Content:MirLua/Example|code=m.UnhookEvent(hHook)}}


=== NotifyEventHooks ===
=== NotifyEventHooks ===
Calls all "traps" of event call sequence one by one.
Calls all hooks of event call sequence one by one.
;Parameters
;Parameters
: '''''hEvent'''''
: '''''hEvent'''''
Line 64: Line 64:
;Result
;Result
: Type: '''boolean'''
: Type: '''boolean'''
: Returns '''true''' if all trap functions were called, else '''false'''.
: Returns '''true''' if all hooks were called, otherwise '''false'''.
;Example
;Example
{{Content:MirLua/Example|code=m.NotifyEventHooks(hEvent)}}
{{Content:MirLua/Example|code=m.NotifyEventHooks(hEvent)}}
Line 78: Line 78:
;Result
;Result
: Type: '''light userdata'''
: Type: '''light userdata'''
: Returns service descriptor if service was created successfully, else '''nil'''.
: Returns service handle if service was created successfully, otherwise '''nil'''.
;Example
;Example
{{Content:MirLua/Example|code=local hService = m.CreateServiceFunction('MyService', function(w, l)
{{Content:MirLua/Example|code=local hService = m.CreateServiceFunction('MyService', function(w, l)
Line 107: Line 107:
;Result
;Result
: Type: '''boolean'''
: Type: '''boolean'''
: Returns '''true''' if service exists, else '''false'''
: Returns '''true''' if service exists, otherwise '''false'''
;Example
;Example
{{Content:MirLua/Example|code=if m.ServiceExists('MyService') then
{{Content:MirLua/Example|code=if m.ServiceExists('MyService') then
Line 132: Line 132:
;Result
;Result
: Type: '''boolean'''
: Type: '''boolean'''
: Returns '''true''' if plugin is loaded, else '''false'''.
: Returns '''true''' if plugin is loaded, otherwise '''false'''.
;Example
;Example
{{Content:MirLua/Example|code=if m.IsPluginLoaded('{F0FDF73A-753D-499d-8DBA-336DB79CDD41}') then
{{Content:MirLua/Example|code=if m.IsPluginLoaded('{F0FDF73A-753D-499d-8DBA-336DB79CDD41}') then

Revision as of 21:30, 14 December 2015

This module is imported into global table and available in any module through variable m. It allows you to access basic features of Miranda NG core.

<translate> Note</translate>
Parameters written in bold italics are obligatory.


Named events

CreateHookableEvent

Creates a hookable event.

Parameters
name
Type: string
Event name.
Result
Type: light userdata
Returns event handle if event was created successfully, otherwise nil.
Example
local hEvent = m.CreateHookableEvent('MyEvent')

HookEvent

Sets a callback function ("hook") to react to event call. Hook are called one by one in the order they were added to the sequence.

Hook signature: function (wParam, lParam) return 0 end.

Correct result for a trap is 0. When 1 is returned, the following hooks in a sequence won't be called.

Parameters
name
Type: string
Event name.
hook
Type: function
Hook function to be called when event occurs.
Result
Type: light userdata
Returns trap handle if trap was created successfully, otherwise nil.
Example
local hHook = m.HookEvent('MyEvent', function(w, l)
  print('MyEvent is raised!')
end)

UnhookEvent

Removes hook from event call sequence.

Parameters
hEvent
Type: light userdata
Event descriptor received on CreateHookableEvent call.
Result
Type: boolean
Returns true if trap function was removed successfully, otherwise false.
Example
m.UnhookEvent(hHook)

NotifyEventHooks

Calls all hooks of event call sequence one by one.

Parameters
hEvent
Type: light userdata
Event descriptor received on CreateHookableEvent call.
wParam
lParam
Result
Type: boolean
Returns true if all hooks were called, otherwise false.
Example
m.NotifyEventHooks(hEvent)


Named service functions

CreateServiceFunction

Creates a service function ("service")

Parameters
name
Type: string
Service name.
Result
Type: light userdata
Returns service handle if service was created successfully, otherwise nil.
Example
local hService = m.CreateServiceFunction('MyService', function(w, l)
  print('MyServiceis called!')
end)

CallService

Calls service with parameters.

Parameters
name
Type: string
Service name.
wParam
lParam
Result
Type: number
Returns result of service execution or CALLSERVICE_NOTFOUND
Example
m.CallService('MyService', 0, 0)

ServiceExists

Checks if service exists by its name.

Parameters
name
Type: string
Service name.
Result
Type: boolean
Returns true if service exists, otherwise false
Example
if m.ServiceExists('MyService') then
  m.CallService('MyService')
end

DestroyServiceFunction

Destroys a service function.

Parameters
hService
Type: light userdata
Service descriptor received on CreateServiceFunction call.
Example
m.DestroyServiceFunction(hService)


Others

IsPluginLoaded

Checks if plugin is loaded by its UUID.

Parameters
uuid
Type: string
Plugin UUID in format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
Result
Type: boolean
Returns true if plugin is loaded, otherwise false.
Example
if m.IsPluginLoaded('{F0FDF73A-753D-499d-8DBA-336DB79CDD41}') then
  print('Advanced auto away plugin is loaded!')
end

Utf8DecodeA

Converts Lua string contents to ANSI (codepage of the current langpack is used).

text
Type: string
Result
Type: string
Example
m.CallService("Quotes/Import", 0, Utf8DecodeA('c:\\quotes.xml'))

Utf8DecodeW

Converts Lua string contents to Unicode (UTF-16).

text
Type: string
Result
Type: string
Example
m.CallService("Popup/ShowMessageW", m.Utf8DecodeW('Hello, World!'), 2)

Translate

Translates a string into the language of the current langpack.

text
Type: string
Result
Type: string
Example
m.Translate('Exit')

ReplaceVariables

Replaces Miranda NG variables in a string.

text
Result
Type: string
Example
local profileName = m.ReplaceVariables('%miranda_profilename%')


Constants

NULL

Null pointer.

Type: light userdata
Example
if hEvent == m.NULL then
  print('Event handle is empty!')
end

INVALID_HANDLE_VALUE

Invalid descriptor.

Type: light userdata
Example
if hEvent == m.NULL then
  print('Event handle is invalid!')
end

CALLSERVICE_NOTFOUND

Result of service call when service does not exist.

Type: number
Example
local result = m.CallService('MyService')
if result == m.CALLSERVICE_NOTFOUND then
  print('Service is not found!')
end
Retrieved from "https://wiki.miranda-ng.org/index.php?title=Plugin:MirLua/Module/m_core&oldid=18164"