DreamShell 4.0 - API Doc

[SWAT]

Полные списки функций без описания можно посмотреть здесь: http://www.dc-swat.net.ru/ds/doc/
В первую очередь постараюсь сделать описание функций ядра DreamShell, ибо описание остальных библиотек есть в инете.

Напоминаю, как и в предыдущей версии DreamShell, функции С в lua доступны в соответствующих названиям модулей объектах.
Допустим все функции модуля DS, доступны в lua через префикс "DS." (без кавычек) и т. д.

[SWAT]

Списки
Файл list.h в SDK.

Списки используются во многих местах DreamShell, в модулях, в событиях, в приложениях, в процессах...
Поэтому я начал с них. Зная принцип их работы, можно будет понять многие связанные функции, без особого труда в дальнейшем.
Итак.


Структура элемента списка

Код:

typedef struct Item {

// Точка входа SLIST, только для внутреннего использования.
SLIST_ENTRY(Item) list;

// Имя элемента списка
char *name;

// ID элемента списка
int id;

// Тип элемента списка
int type;

// Данные элемента списка
void *data;

} Item_t;

Определение типа для списка, используется SLIST из стандартной newlib библиотеки

Код:

typedef SLIST_HEAD(ItemList, Item) Item_list_t;

Определение типа функции, освобождающей память, занимаемую данными элемента.

Код:

typedef void listFreeItemFunc(void *);

Определенные типы данных элемента, которые есть в DreamShell, вы можете добавлять свои.
Если вы используете список, где данные элемента не подходят не под один существующий тип,
то можно использовать универсальный тип LIST_ITEM_USERDATA.

Код:

#define LIST_ITEM_USERDATA 0
#define LIST_ITEM_SDL_SURFACE 1

#define LIST_ITEM_GUI_SURFACE 2
#define LIST_ITEM_GUI_FONT 3
#define LIST_ITEM_GUI_WIDGET 4

#define LIST_ITEM_MODULE 5
#define LIST_ITEM_APP 6
#define LIST_ITEM_EVENT 7
#define LIST_ITEM_THREAD 8

Создает список и возвращает указатель на него. Возвращает NULL в случае не удачи.

Код:

Item_list_t *listMake();

Удаляет все элементы списка и сам список, аргумент ifree является функцией, для освобождения памяти, которую занимают данные элемента.
В основном подходит функция free, она же используется там по умолчанию, если указать вместо аргумента ifree - NULL

Код:

void listDestroy(Item_list_t *lst, listFreeItemFunc *ifree);

Получает ID последнего элемента (существующего или уже нет) из списка.

Код:

int listGetLastId(Item_list_t *lst);

Добавляет элемент в список и возвращает ссылку на него при успехе, а при ошибке возвращает NULL.

Код:

Item_t *listAddItem(Item_list_t *lst, int type, char *name, void *data);

Удаляет элемент из списка.

Код:

void listRemoveItem(Item_list_t *lst, Item_t *i, listFreeItemFunc *ifree);

Ищет элемент в списке по его имени.
Если элемент найден, возвращается ссылка на него, если же нет, то возвращает NULL.

Код:

Item_t *listGetItemByName(Item_list_t *lst, char *name);

Ищет элемент в списке по его ID.
Если элемент найден, возвращается ссылка на него, если же нет, то возвращает NULL.

Код:

Item_t *listGetItemById(Item_list_t *lst, int id);

Возвращает первый элемент списка.

Код:

Item_t *listGetItemFirst(Item_list_t *lst);

Возвращает следующий элемент списка, находящийся после элемента переданного аргументом i.

Код:

Item_t *listGetItemNext(Item_t *i);

Примечание:
Функции listGetItemFirst и listGetItemNext служат для создания циклической обработки списков.