From 9eed9f0d246f44a51266a05e0107ea22fea54e73 Mon Sep 17 00:00:00 2001
From: Alexander Gavrilov
Date: Thu, 5 Apr 2012 19:55:59 +0400
Subject: [PATCH] Wrap a few utility functions defined on the c++ side for lua.
---
LUA_API.rst | 61 ++++++++++++++++++++++++++++++++++++
Lua API.html | 58 ++++++++++++++++++++++++++++++++++
library/LuaTools.cpp | 48 +++++++++++++++++++++++++++-
library/LuaTypes.cpp | 33 ++++++++++++++++---
library/MiscUtils.cpp | 5 +++
library/include/DataFuncs.h | 9 +++++-
library/include/Error.h | 12 +++++++
library/include/LuaWrapper.h | 11 +++++--
library/lua/dfhack.lua | 26 +++++++++++++++
library/modules/Job.cpp | 15 +++++++++
10 files changed, 268 insertions(+), 10 deletions(-)
diff --git a/LUA_API.rst b/LUA_API.rst
index bf6c81ec0..dab299741 100644
--- a/LUA_API.rst
+++ b/LUA_API.rst
@@ -497,3 +497,64 @@ Since the data is hidden in data structures owned by the DF world,
and automatically stored in the save game, these save and retrieval
functions can just copy values in memory without doing any actual I/O.
However, currently every entry has a 180+-byte dead-weight overhead.
+
+C++ function wrappers
+=====================
+
+Thin wrappers around C++ functions, similar to the ones for virtual methods.
+
+Gui module
+----------
+
+* ``dfhack.gui.getSelectedWorkshopJob(silent)``
+
+ When a job is selected in *'q'* mode, returns the job, else
+ prints error unless silent and returns *nil*.
+
+* ``dfhack.gui.getSelectedJob(silent)``
+
+ Returns the job selected in a workshop or unit/jobs screen.
+
+* ``dfhack.gui.getSelectedUnit(silent)``
+
+ Returns the unit selected via *'v'*, *'k'*, unit/jobs, or
+ a full-screen item view of a cage or suchlike.
+
+* ``dfhack.gui.getSelectedItem(silent)``
+
+ Returns the item selected via *'v'* ->inventory, *'k'*, *'t'*, or
+ a full-screen item view of a container. Note that in the
+ last case, the highlighted *contained item* is returned, not
+ the container itself.
+
+* ``dfhack.gui.showAnnouncement(text,color,is_bright)``
+
+ Adds a regular announcement with given text, color, and brightness.
+ The is_bright boolean actually seems to invert the brightness.
+
+* ``dfhack.gui.showPopupAnnouncement(text,color,is_bright)``
+
+ Pops up a titan-style modal announcement window.
+
+Job module
+----------
+
+* ``dfhack.job.cloneJobStruct(job)``
+
+ Creates a deep copy of the given job.
+
+* ``dfhack.job.printJobDetails(job)``
+
+ Prints info about the job.
+
+* ``dfhack.job.getJobHolder(job)``
+
+ Returns the building holding the job.
+
+* ``dfhack.job.is_equal(job1,job2)``
+
+ Compares important fields in the job and nested item structures.
+
+* ``dfhack.job.is_item_equal(job_item1,job_item2)``
+
+ Compares important fields in the job item structures.
diff --git a/Lua API.html b/Lua API.html
index 25b6f06d6..877bdbd88 100644
--- a/Lua API.html
+++ b/Lua API.html
@@ -335,6 +335,11 @@ ul.auto-toc {
DFHack utilities
@@ -753,6 +758,59 @@ and automatically stored in the save game, these save and retrieval
functions can just copy values in memory without doing any actual I/O.
However, currently every entry has a 180+-byte dead-weight overhead.
+
+
+
Thin wrappers around C++ functions, similar to the ones for virtual methods.
+
+
+
+dfhack.gui.getSelectedWorkshopJob(silent)
+When a job is selected in 'q' mode, returns the job, else
+prints error unless silent and returns nil.
+
+dfhack.gui.getSelectedJob(silent)
+Returns the job selected in a workshop or unit/jobs screen.
+
+dfhack.gui.getSelectedUnit(silent)
+Returns the unit selected via 'v', 'k', unit/jobs, or
+a full-screen item view of a cage or suchlike.
+
+dfhack.gui.getSelectedItem(silent)
+Returns the item selected via 'v' ->inventory, 'k', 't', or
+a full-screen item view of a container. Note that in the
+last case, the highlighted contained item is returned, not
+the container itself.
+
+dfhack.gui.showAnnouncement(text,color,is_bright)
+Adds a regular announcement with given text, color, and brightness.
+The is_bright boolean actually seems to invert the brightness.
+
+dfhack.gui.showPopupAnnouncement(text,color,is_bright)
+Pops up a titan-style modal announcement window.
+
+
+
+
+
+
+dfhack.job.cloneJobStruct(job)
+Creates a deep copy of the given job.
+
+dfhack.job.printJobDetails(job)
+Prints info about the job.
+
+dfhack.job.getJobHolder(job)
+Returns the building holding the job.
+
+dfhack.job.is_equal(job1,job2)
+Compares important fields in the job and nested item structures.
+
+dfhack.job.is_item_equal(job_item1,job_item2)
+Compares important fields in the job item structures.
+
+
+
+