Add readme
This commit is contained in:
216
README.md
Normal file
216
README.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# LibFreeMedia
|
||||
|
||||
LibFreeMedia is a small library to facilitate the sharing of media resources
|
||||
between different World of Warcraft addons. It was developed to provide a free
|
||||
software alternative to the proprietary LibSharedMedia.
|
||||
|
||||
Sharing media works best for both users as well as addon developers if everyone
|
||||
can access the shared media pool equally, and this includes authors that want
|
||||
to release their addons as free software. Therefore this library interoperates
|
||||
with LibShareMedia. Media registered using one library can be retrieved with
|
||||
the other and vice versa. See [Interopability](#interopability) for the
|
||||
limitations of this interopability.
|
||||
|
||||
# API
|
||||
|
||||
LibFreeMedia registers as a library using LibStub. Use LibStub to acquire a
|
||||
handle to the libary:
|
||||
```lua
|
||||
local lib = LibStub:GetLibrary("LibFreeMedia")
|
||||
```
|
||||
|
||||
## Registering Media
|
||||
|
||||
```lua
|
||||
lib:Register(kind, identifier, data)
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
* *kind* (string): the kind of media you are registering. Some examples are
|
||||
"font", "background" or "statusbar"
|
||||
* *identifier* (string): The (unique among its kind) name to identify the
|
||||
media. Users will often see this name, so use a descriptive name.
|
||||
* *data* (any): The data that represents the media. After it is registered
|
||||
the library takes ownership of the data and it _must not_ be changed.
|
||||
|
||||
### Return value
|
||||
|
||||
The return value is a boolean indicating whether the media was registered
|
||||
successfully. Failure may happen for a number of reasons, including registering
|
||||
invalid data or the identifier already has registered media for that kind.
|
||||
|
||||
### Example
|
||||
|
||||
```lua
|
||||
local libfm = LibStub:GetLibrary("LibFreeMedia")
|
||||
libfm:Register("font", "Roboto Regular", "Interface\\AddOn\\MyAddon\\Fonts\\Roboto Regular.ttf")
|
||||
libfm:Register("font", "Roboto Bold", "Interface\\AddOn\\MyAddon\\Fonts\\Roboto Bold.ttf")
|
||||
|
||||
if not libfm:Register("font", "Roboto Bold", "Interface\\AddOn\\MyAddon\\Fonts\\Roboto Bold.ttf") then
|
||||
error("The media registration failed")
|
||||
end
|
||||
```
|
||||
|
||||
## Getting individual media
|
||||
|
||||
```lua
|
||||
lib:Get(kind, identifier)
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
* *kind* (string): the kind of media you want to retrieve. Some examples are
|
||||
"font", "background" or "statusbar".
|
||||
* *identifier* (string): The name of the media you want to retrieve.
|
||||
|
||||
### Return value
|
||||
|
||||
If the media exists, its data is returned. The type of this data depends on the
|
||||
kind of media. LibFreeMedia retains ownership of this data and you _must not_
|
||||
alter it in place.
|
||||
|
||||
If the media does not exist the function will return `nil`.
|
||||
|
||||
### Examples
|
||||
|
||||
```lua
|
||||
local libfm = LibStub:GetLibrary("LibFreeMedia")
|
||||
|
||||
local robotoRegular = libfm:Get("font", "Roboto Regular")
|
||||
if robotoRegular then
|
||||
print("Successfully got the font location:", robotoRegular)
|
||||
else
|
||||
print("The 'Roboto Regular' font could not be retrieved")
|
||||
end
|
||||
```
|
||||
|
||||
## Getting a list of media identifiers
|
||||
|
||||
```lua
|
||||
lib:GetList(kind)
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
* *kind* (string): the kind of media you want to get a list of. Some examples
|
||||
are "font", "background" or "statusbar".
|
||||
|
||||
### Return value
|
||||
|
||||
If there is media registered for the requested kind it will be returned as a
|
||||
sorted sequence table of media identifiers for the requested kind. If there is
|
||||
no media of the requested kind then this function will return either `nil` or
|
||||
an empty table.
|
||||
|
||||
LibSharedMedia retains ownership of the returned tables and they should not be
|
||||
altered in place. These tables may be reused by LibSharedMedia and and media
|
||||
that is registered in the future could be added to these tables but this behavior
|
||||
_should not_ be relied on. If you require an up to date list, call the
|
||||
library to receive one. If you require a snapshot to remain static, make a deep
|
||||
copy.
|
||||
|
||||
### Examples
|
||||
|
||||
```lua
|
||||
local libfm = LibStub:GetLibrary("LibFreeMedia")
|
||||
|
||||
local fonts = libfm:GetList("font")
|
||||
if fonts == nil or #fonts == 0 then
|
||||
print("No registered fonts found")
|
||||
else
|
||||
print("Registered fonts", table.concat(fonts, ", "))
|
||||
end
|
||||
```
|
||||
|
||||
## Getting a table of media data
|
||||
|
||||
```lua
|
||||
lib:GetTable(kind)
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
* *kind* (string): the kind of media you want to get a list of. Some examples
|
||||
are "font", "background" or "statusbar".
|
||||
|
||||
### Return value
|
||||
|
||||
If there is media registered for the requested kind it will be returned as a
|
||||
table with identifier:data pairs. If there is no media of the requested kind
|
||||
then this function will return either `nil` or an empty table.
|
||||
|
||||
LibSharedMedia retains ownership of the returned tables and they should not be
|
||||
altered in place. These tables may be reused by LibSharedMedia and and media
|
||||
that is registered in the future could be added to these tables but this behavior
|
||||
_should not_ be relied on. If you require an up to date list, call the
|
||||
library to receive one. If you require a snapshot to remain static, make a deep
|
||||
copy.
|
||||
|
||||
### Examples
|
||||
|
||||
```lua
|
||||
local libfm = LibStub:GetLibrary("LibFreeMedia")
|
||||
|
||||
local fonts = libfm:GetTable("font") or {}
|
||||
|
||||
for identifier, data in pairs(fonts) do
|
||||
print(identifier, data)
|
||||
end
|
||||
```
|
||||
|
||||
# Embedding LibFreeMedia
|
||||
|
||||
The recommended way to include LibFreeMedia in your addon is embedding it and
|
||||
getting a handle using LibStub. To do this you To do this simply grab one of
|
||||
the embed archives from the
|
||||
[releases](https://gitlab.com/omicron-oss/wow/libfreemedia/-/releases) and
|
||||
extract these files in your addon. Do the same with
|
||||
[LibStub](https://www.wowace.com/projects/libstub). This will get you a
|
||||
directory tree similar to the following:
|
||||
|
||||
```
|
||||
YourAddon/libs/LibFreeMedia/LibFreeMedia.lua
|
||||
YourAddon/libs/LibStub/LibStub.lua
|
||||
YourAddon/YourAddon.toc
|
||||
...
|
||||
```
|
||||
|
||||
Simply add `LibStub.lua` and `LibFreeMedia.lua` as the first few files in your
|
||||
`YourAddon.toc` as follows:
|
||||
|
||||
```
|
||||
## Interface: 100100
|
||||
## Title: YourAddon
|
||||
## Version: 4.20.69
|
||||
|
||||
# List LibStub and then LibFreeMedia
|
||||
libs/LibStub/LibStub.lua
|
||||
libs/LibStub/LibFreeMedia.lua
|
||||
|
||||
# List all your addon files as desired
|
||||
```
|
||||
|
||||
# Interopability
|
||||
|
||||
Since it is in the interested of both users and developers to not create
|
||||
additional pools for shared media, LibFreeMedia attempts to interoperate
|
||||
seamlessly with LibSharedMedia. However, there is no 100% parity between
|
||||
LibFreeMedia and LibSharedMedia. This section will list all the areas where
|
||||
LibFreeMedia differs from LibSharedMedia.
|
||||
|
||||
LibFreeMedia does not support making callbacks on media registration. Any addon
|
||||
that relies on these callbacks in LibSharedMedia will currently not receive
|
||||
notifications when media is registered using LibFreeMedia. This is likely
|
||||
temporary, see issue #1.
|
||||
|
||||
LibFreeMedia does not support default return values for missing media, nor does
|
||||
it allow you to register a particular piece of media as the default for a
|
||||
specific kind.
|
||||
|
||||
LibFreeMedia does not support language masks for font registration. This is not
|
||||
likely to change.
|
||||
|
||||
LibFreeMedia does not attempt to be a drop-in replacement for LibSharedMedia.
|
||||
The API behaves slightly different. If there is demand for a drop-in
|
||||
replacement then this could change.
|
||||
Reference in New Issue
Block a user