alpha
/
Kaleidoscope
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'ba47ccf4e5'
${ noResults }
Kaleidoscope/src/kaleidoscope_internal/deprecations.h

86 lines
4.2 KiB
Raw Normal View History Unescape

License clarificataion & copyright headers After talking with Jesse, this changes the license to GPLv3 (only), where appropriate, and adds copyright headers to all files that were missing them. Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
6 years ago
/* Kaleidoscope - Firmware for computer input devices
* Copyright (C) 2013-2018 Keyboard.io, Inc.
*
* This program is free software: you can redistribute it and/or modify it under
* the terms of the GNU General Public License as published by the Free Software
* Foundation, version 3.
*
* This program is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
* FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
* details.
*
* You should have received a copy of the GNU General Public License along with
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
Move deprecation messages to a separate header Moving the deprecation messages to a separate header, and adding a few helpers allow us to write much more detailed deprecation messages, without needlessly making the code look incredibly messy. This also updates most of the deprecation messages to be much more helpful, and provide hints at how to fix the warnings produced by them. Signed-off-by: Gergely Nagy <algernon@keyboard.io>
7 years ago
#pragma once
#define DEPRECATED(tag) \
__attribute__((deprecated(_DEPRECATE(_DEPRECATED_MESSAGE_ ## tag))))
#define _DEPRECATE(message) "\n" \
"------------------------------------------------------------------------\n" \
message \
"\n" \
"------------------------------------------------------------------------\n" \
/* Messages */
Deprecate named hardware objects Some boards used to provide the device object under an alias named after the device itself. For the sake of consistency, we do not want to provide these aliases in the future. As such, deprecate them, and update all users to use `KeyboardHardware` instead. Signed-off-by: Gergely Nagy <algernon@keyboard.io>
5 years ago
Deprecate the old `kaleidoscope::hid` facade Signed-off-by: Gergely Nagy <algernon@keyboard.io>
5 years ago
#define _DEPRECATED_MESSAGE_HID_FACADE __NL__ \
"The HID facade in the `kaleidoscope::hid` namespace is deprecated.\n" __NL__ \
"Please use `Kaleidoscope.hid()` instead."
Deprecate a few older symbols `KeyboardHardware`, `ROWS`, `COLS`, and `LED_COUNT` have been deprecated. Signed-off-by: Gergely Nagy <algernon@keyboard.io>
5 years ago
#define _DEPRECATED_MESSAGE_NAMED_HARDWARE __NL__ \
"Named hardware objects are deprecated, please use\n" __NL__ \
"`Kaleidoscope.device()` instead."
#define _DEPRECATED_MESSAGE_KEYBOARDHARDWARE \
"`KeyboardHardware` is deprecated, please use\n" __NL__ \
"`Kaleidoscope.device()` instead"
Redesign of the device plugin APIs The new device APIs were built on top of composition (instead of inheritance, like the former one). At the highest level, we have `kaleidoscope::device::Base` and `kaleidoscope::device::BaseProps`. The latter is a set of overrideable properties, components that make up the device: the key scanner, LEDs, MCU, and so on. Many components - like the key scanner and LEDs - also come in a similar setup: the base class and properties, because this allows us to make them fairly efficient templates. All of the existing devices have been ported to the new APIs. While the old `Hardware` base class remains - for now, and deprecated - it is not guaranteed to work. Signed-off-by: Gergely Nagy <algernon@keyboard.io>
5 years ago
#define _DEPRECATED_MESSAGE_HARDWARE_RESETDEVICE \
"`KeyboardHardware.resetDevice()` is deprecated, please use " __NL__ \
"`Kaleidoscope.rebootBootloader()` instead."
Deprecate a few older symbols `KeyboardHardware`, `ROWS`, `COLS`, and `LED_COUNT` have been deprecated. Signed-off-by: Gergely Nagy <algernon@keyboard.io>
5 years ago
#define _DEPRECATED_MESSAGE_ROWS \
"The `ROWS` macro is deprecated, please use\n" __NL__ \
"`Kaleidoscope.device().matrix_rows` instead."
#define _DEPRECATED_MESSAGE_COLS \
"The `COLS` macro is deprecated, please use \n" __NL__ \
"`Kaleidoscope.device().matrix_columns` instead."
#define _DEPRECATED_MESSAGE_LED_COUNT \
"The `LED_COUNT` macro is deprecated, please use \n" __NL__ \
"`Kaleidoscope.device().led_count` instead."
Redesign of the device plugin APIs The new device APIs were built on top of composition (instead of inheritance, like the former one). At the highest level, we have `kaleidoscope::device::Base` and `kaleidoscope::device::BaseProps`. The latter is a set of overrideable properties, components that make up the device: the key scanner, LEDs, MCU, and so on. Many components - like the key scanner and LEDs - also come in a similar setup: the base class and properties, because this allows us to make them fairly efficient templates. All of the existing devices have been ported to the new APIs. While the old `Hardware` base class remains - for now, and deprecated - it is not guaranteed to work. Signed-off-by: Gergely Nagy <algernon@keyboard.io>
5 years ago
#define _DEPRECATED_MESSAGE_HARDWARE_BASE_CLASS \
Key union converted to a proper class Unions are a C-reminiscense that are better avoided in modern C++. They cause specific problems due to their nature of representing independent types. The way they are used in Kaleidoscope, they can easily be replaced by a class. This enables it to properly work with Key objects in constexpr context where with the old union-based implementation the compiler reported errors when one Key was constructed based on a key_code/flags pair and another one through raw-data. In such a case, the compiler assumes that both Key instances represent something entirely different. This is because unions were never meant for type conversions and the C++ standard considers their use for that purpose as undefined behavior. The new class provides accessor methods for raw-data access and for key_code/flags-data access. This is a breaking change as it is is not possible to replace direct member access patterns like key.raw = 0xFFFF; based on the raw-accessors. For the .keyCode and .flags members, proxy objects are used to enable the generation of suitable deprecations warnings. All direct access via .raw, .keyCode and .flags have been replaced throughout Kaleidoscope. Information on how to upgrade is provided in UPGRADING.md Signed-off-by: Florian Fleissner <florian.fleissner@inpartik.de>
5 years ago
"The `Hardware` base class is deprecated. Please use\n" __NL__ \
Redesign of the device plugin APIs The new device APIs were built on top of composition (instead of inheritance, like the former one). At the highest level, we have `kaleidoscope::device::Base` and `kaleidoscope::device::BaseProps`. The latter is a set of overrideable properties, components that make up the device: the key scanner, LEDs, MCU, and so on. Many components - like the key scanner and LEDs - also come in a similar setup: the base class and properties, because this allows us to make them fairly efficient templates. All of the existing devices have been ported to the new APIs. While the old `Hardware` base class remains - for now, and deprecated - it is not guaranteed to work. Signed-off-by: Gergely Nagy <algernon@keyboard.io>
5 years ago
"the new APIs based on `kaleidoscope::device::Base`."
Key union converted to a proper class Unions are a C-reminiscense that are better avoided in modern C++. They cause specific problems due to their nature of representing independent types. The way they are used in Kaleidoscope, they can easily be replaced by a class. This enables it to properly work with Key objects in constexpr context where with the old union-based implementation the compiler reported errors when one Key was constructed based on a key_code/flags pair and another one through raw-data. In such a case, the compiler assumes that both Key instances represent something entirely different. This is because unions were never meant for type conversions and the C++ standard considers their use for that purpose as undefined behavior. The new class provides accessor methods for raw-data access and for key_code/flags-data access. This is a breaking change as it is is not possible to replace direct member access patterns like key.raw = 0xFFFF; based on the raw-accessors. For the .keyCode and .flags members, proxy objects are used to enable the generation of suitable deprecations warnings. All direct access via .raw, .keyCode and .flags have been replaced throughout Kaleidoscope. Information on how to upgrade is provided in UPGRADING.md Signed-off-by: Florian Fleissner <florian.fleissner@inpartik.de>
5 years ago
#define _DEPRECATED_MESSAGE_DIRECT_KEY_MEMBER_ACCESS \
"Direct access to `Key` class' data members is deprecated.\n" \
"Please use `Key::setKeyCode()`/`Key::getKeyCode()` or\n" \
"`Key::setFlags()`/`Key::getFlags()` instead.\n" \
"\n" \
"For further information and examples on how to do that, \n" \
"please see UPGRADING.md."
#define _DEPRECATED_MESSAGE_KEY_MEMBER_RAW_ACCESS \
"The member variable `raw` of class Key had to be removed. Please \n" \
"use `Key::setRaw()`/`Key::getRaw()` to set and get raw data.\n" \
"\n" \
"Important: This is not a deprecation. Your code will compile but fail\n" \
" to link until all access to `Key::raw` has been replaced.\n" \
"\n" \
"For further information and examples on how to do that, \n" \
"please see UPGRADING.md."
Extracted and renamed class Kaleidoscope->Runtime This was done to enable separate inclusion of the central runtime class without having to include the central header kaleidoscope/Kaleidoscope.h which used to pull in a lot of stuff that is not required in many compilation units. The new class `Runtime_` lives in namespace kaleidoscope its singleton instance is `kaleidoscope::Runtime`. It is now only available internally in library Kaleidoscope but not from the sketch. The original class name `Kaleidoscope_` in global scope has been deprecated. The original instance name `Kaleidoscope` in global scope has been preserved to be used by end users in their sketches. Signed-off-by: Florian Fleissner <florian.fleissner@inpartik.de>
5 years ago
#define _DEPRECATED_MESSAGE_GLOBAL_VARIABLE_KALEIDOSCOPE \
"Variable `Kaleidoscope` in global namespace has been deprecated.\n" \
"Please use `kaleidoscope::Runtime` instead."
#define _DEPRECATED_MESSAGE_GLOBAL_TYPENAME_KALEIDOSCOPE \
"Type `Kaleidoscope_` in global namespace has been deprecated.\n" \
"Please use `kaleidoscope::Runtime_` instead."